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PREFACE 



This publication describes the subprograms available to users of the 
CRAY-1 and CRAY X-MP Computer Systems* It also contains subprograms that 
allow the translation of a subset of International Business Machines 
(IBM) or Control Data Corporation (CDC) file types online to a Cray 
Computer System. 

The user of this manual is assumed to be familiar with the Cray Operating 
System (COS) , and either the Cray FORTRAN Compiler (CFT) , or the Cray 
Assembly Language (CAL) . The following Cray Research publications might 
be helpful: 

CRAY-OS Version 1 Reference Manual, publication SR-0011 

Macros and Opdefs Reference Manual, publication SR-0012 

FORTRAN (CFT) Reference Manual, publication SR-0009 

CAL Assembler Version 1 Reference Manual, publication SR-0000 

CRAY-OS Message Manual, publication SR-0039 

SKOL Reference Manual, publication SR-0033 

COS Table Descriptions Internal Reference Manual, publication SM-0045 
Pascal Reference Manual, publication SR-0060 



t This manual is available only on tape. See your CRI site analyst for 
information. 
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INTRODUCTION 



1 



This manual describes the subprograms provided in the standard libraries, 
$ARLIB, $FTLIB, $IOLIB r $SCILIB r $SYSLIB, and $UTLIB. Routines generated 
by CFT in the form of inline code are not included in this manual but are 
described in the FORTRAN (CFT) Reference Manual, CRI publication SR-0009. 

Section 2 provides a subprogram summary grouped alphabetically by primary 
reference name within each library. Sections 3 through 7 provide 
detailed descriptions and calling sequences of the subprograms listed in 
section 2. Sections 3 through 6 cover specific subprogram applications 
and common mathematics, scientific mathematics, input/output, and dataset 
management. Section 7 is a collection of special purpose subprograms, 
grouped by application. These applications are debugging aids, job 
control, floating-point interrupt control, time and date requests, and 
control statement processing* The last subsection in section 7 consists 
of routines whose applications do not lend themselves to any particular 
grouping and are therefore listed separately. Section 8 presents 
procedures and functions that reside in the Pascal runtime library, 
$PSCLIB. Section 9 describes multitasking subprograms. 



SUBPROGRAM CLASSIFICATION 

The subprograms described in this manual are either subroutines, scalar 
functions, or vector functions. Some subprograms can be used as either 
subroutines or scalar functions. Scalar functions produce a single 
result while vector functions produce a vector of results. Some vector 
functions (called paeudo vector functions) call the corresponding 
scalar functions. Such a scalar function call can occur when the vector 
function performs infrequently used calculations or when the calculation 
is not suited to vector ization. 

In general, arguments to vector call-by-value functions are passed in V 
registers? scalar arguments are broadcast if necessary. However, some 
routines implicitly called by CFT, such as exponentiation, have mixed 
scalar and vector arguments* 
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CFT LINKAGE METHODS 



The CPT-caliable library routines are accessed by one of two methods: 
call-by-address or call-by-value. Subroutines are always accessed by the 
call-by-address method. Library functions intrinsic to CFT, or user 
functions named in a VFUNCTION directive , are accessed by CFT in either 
call-by-address or call-by-value mode, depending on context. 

In call-by-value mode r arguments are loaded into either S or V registers, 
and the function returns its result in SI or Vl (S2 or V2 are also used 
for complex or double-precision functions) . Vector functions must also 
have the vector length present in the VL register. 

In call-by-address mode, addresses of arguments are stored sequentially 
in memory. Under the CFT 1.10 version of the calling sequence, the 
address of the first argument is stored at entry 1, the second at entry 
2, etc. Under the CFT 1.11 version, the list of addresses is stored in a 
block of memory allocated for that purpose. Functions return their 
results in registers. Subroutines return results through their argument 
lists. (For information on the new calling sequence, see the Macros and 
Opdefs Reference Manual, CRI publication SR-0012.) 

By convention a call-by-value has a % suffix (for example, SIN%) , and a 
vector call-by-value has a % prefix and suffix as shown below. 



Type 


Call by 
Address 


Call by 
Value 


Scalar 


RTE 


RTE% 


Vector 


%RTE 

. . . . . 


%RTE% 



Routines that are accessible from CAL programs only also can be prefixed 
with a $. 



CFT LINKAGE MACROS 

CFT linkage macros generate code to handle subprogram linkage between 
CFT-compiled routines and CAL-assembled routines. These linkage macros 
and their uses follow. 

CALL Provides linkage to call-by-address routines 

CALLV Provides linkage to call-by-value routines 
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ENTER Reserves space for parameter addresses, saves B and T 
registers, and sets up traceback linkage 

EXIT Initiates a return from a routine to its caller? restores 

any B or T registers not considered scratch by CFT. 

CFT linkage macros should be used whenever possible to maintain 
compatibility across versions of CFT. See the Macros and Opdefs 
Reference Manual, CRI publication SR-0012, for detailed descriptions of 
CFT linkage macros and linkage conventions. 

All $ARLIB, $FTLIB, $IOLIB, $SCILIB, $UTLIB, and $SYSLIB subroutines can 
use any of the A, S, V, VL, and VM registers as scratch registers; 
therefore, the calling routine should not depend on any of these 
registers being preserved. However, these routines preserve the contents 
of registers B01 through B65 8 and TOO through T67 8 . Registers B70 8 
through B77 8 and T70 8 through T77g also can be used as scratch 
registers. 



NOTE 

Cray Research, Inc., reserves the right to make future 
use of any of the A, S, V, VL, VM, B66-B77, and T70-T77 
registers in any library subroutine. Users cannot 
depend on the contents of these registers being 
preserved by any library routine* 



CONVENTIONS 

The following conventions are used in this manual. 
Convention Description 

Italics Define generic terms representing words or 

symbols to be supplied by the user and 
identify new terms 

[] Brackets Enclose optional portions of a command format 

(SI), (S2) , etc. Content of register SI, S2, etc., respectively 

Arguments are used on entry unless exit or return conditions are 
specified. 
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SUBPROGRAM SUMMARY 



2 



INTRODUCTION 

This section summarizes the subprograms in this manual. These 
subprograms are callable from CAL or Cray FORTRAN programs and reside in 
the $ARLIB, $FTLIB, $IOLIB, $UTLIB, $SYSLIB, and $SCILIB libraries. 

$ARLIB contains routines primarily concerned with returning some numeric 
result. Mathematical routines intrinsic to FORTRAN such as SIN reside 
here, 

$FTLIB contains CFT-specific routines such as ICHAR, LEN, and LOC. 

$IOLIB contains routines that move data from external devices to main 
memory or control that movement. 

$UTLIB contains routines more infrequently used and of a utilitarian 
nature. 

$SCILIB routines perform operations such as matrix multiply or Fast 
Fourier transform and must be explicitly called. Such processes are not 
intrinsic properties of the Cray FORTRAN language and are independent of 
specific Cray Operating System (COS) features. 

$SYSLIB routines usually link directly to the operating system through a 
normal exit. These routines are not usually accessible from a Cray 
FORTRAN program, but are called by $IOLIB and $UTLIB routines for 
specific tasks. In general/ $SYSLIB serves as a link between the general 
purpose $I0LIB and $UTLIB routines and the details of COS. $SYSLIB 
routines depend on specific COS features. 

Subprograms implicitly called by a CFT routine (for example, routines 
used for exponentiation or I/O) have a $ or % character in their 
names. They are not directly callable by a Cray FORTRAN program. 



TABLE DESCRIPTION 

Table 2-1 contains the subprogram summary that includes the following 
items. 
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• Primary reference name 

• Page number 

• UPDATE deck name 

• Entry type 

• CFT call type 

• Library 

• OS dependency 

• Purpose 



PRIMARY REFERENCE NAME 

Primary reference name is a general group name identifying a subprogram 
and is generally similar to the subprogram name. For example, BACKSP is 
the primary reference name for the backspace subprograms BACK/ $BACK, 
BKFILE, BKSP, $BKSP, and BKSPF. The subprograms are alphabetized by 
primary reference name. 



PAGE NUMBER 

The page numbers of subprogram locations are listed under each primary 
reference name and reference detailed descriptions of the subprogram. 



UPDATE DECK NAME 

UPDATE deck name is the listed name of the subprogram in the UPDATE 
program library. 



ENTRY TYPE 

Entry type indicates the source of the subprogram call, either CFT or 
CAL. Entries callable from CFT are further divided into (1) 
call-by-address and (2) call-by-value. See the description of these 
linkage methods in the introduction to this manual. 
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CFT CALL TYPE 

CFT call type indicates three classifications for CFT callable 
subprograms; 

S Subroutine 

SF Scalar function 

VF Vector function 

See the introduction to this manual for a description of these 
classifications. 



LIBRARY 

The library column indicates the library residence of the subprogram. 



OS DEPENDENCY 

Each subprogram is labeled either OS dependent (Dep.) or OS independent 
(Ind.). This classification is a guideline for use of the routine under 
operating systems other than the current version of COS. Independent 
routines can be executed under other operating systems with minor changes 
such as macro redefinition or substitution of external routines. 
Dependent routines rely heavily on COS features. 



PURPOSE 

The purpose is a 1- or 2-line description of the subprogram. 



PASCAL SUBPROGRAMS 

Table 2-2 summarizes Pascal subprograms with a format similar to that of 
table 2-1. Exceptions are (1) the primary reference name and UPDATE deck 
name are always the same; (2) those subprograms callable from CAL only 
are indicated with an X; and (3) the library is $PSCLIB for all Pascal 
subprograms. 
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Table 2-1 ♦ Subprogram summary 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CPT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


ABORT 


ABORT 


ABORT 






S 


$UTLIB 


Ind. 


Aborts job with traceback 


ABS 


REAL 


ABS 






SP 


$ARLIB 


Ind. 


Computes absolute value 




ACCESS 


ACS 


ACCESS 


____________ — 


_«___________________. 


S 


$SYSLIB 


Dep. 


Accesses a permanent dataset 




ACOS 
ACOSV 


ACOS 


ACOS% 
%ACOS% 


%ACOS 


SP 
VF 


$ARLIB 
$ARLIB 


ind. 
Ind. 


Computes arccosine 
Computes vectorized 
arccosine 


ACPTRAD 


RCVRBAD 


ACPTBAD 




_________ 


S 


$SYSLIB 


Dep. 


Transfers bad data to a 
specified buffer for the 
caller 
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Table 2-1* Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 
Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 




value 


ACQUIRE 


AQR 


anon tot? 






S 


$SYSLIB 


Dep* 


Accesses a permanent 
dataset or acquires a 
front-end resident dataset 
and stages it to the Cray 
mainframe 


ACTTABLE 


ACTTABLE 


ACTTABLE 






s 


$SYSLIB 


Dep. 


Returns job accounting table 


ADJUST 


ADJ 


ADJUST 






s 


$SYSLIB 


Dep. 


Expands or contracts a 
permanent dataset 


AIMAG 

1 


COMPLX 


AIMAG 






SF 


$ARLIB 


Ind. 


Returns imaginary part of a 
complex number 


AINT 


REAL 


AINT 






SF 


$ARLIB 


Ind. 


Truncates to integral value 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 

Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


call From 
CAL Only 


Address 


Value 


ALF 


ALF 


ADDLFT 




$ALF 


S 


$SYSLIB 


Dep. 


Adds name to Logical File 
Table (LFT) 


AMOD 


REAL 


AMOD 






SF 


$ARLIB 


Ind. 


Computes division remainder 


AMU 


TM 






$AMU 




$SYSLIB 


Dep. 


Returns total allotted 
table space 


AND 


BOOLEAN 


AND 






SF 


$ARLIB 


Ind. 


Forms logical product 


AN INT 


REAL 


ANINT 






SA 


$ARLIB 


ind. 


Calculates nearest whole 
number 


ARERP 


ARERP 






ARERP% 




$ARLIB 


Dep. 


Processes $ARLIB errors 
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Table 2-1 • Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


ARGPLIMQ 


FLOW 


ARGPLIMQ 






S 


$UTLIB 


Ind. 


Controls listing of 
argument values for every 
call and return 


ASCDC 


ASCDC 


ASCDC 






S 


$UTLIB 


Ind. 


Converts ASCII character to 
display code character 


ASIN 


ACOS 
ACOSV 


ASIN 


ASIN% 
%ASIN% 


%ASIN 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Computes arcsine 

Computes vectorized arcsine 


ASSIGN 


ASS 


ASSIGN 






S 


$SYSLIB 


Dep. 


Opens dataset and assigns 
characteristics to it 


ATAN 


ATAN 
ATANV 


ATAN 


ATAN% 
%ATAN% 


%ATAN 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Computes arctangent 
Computes vectorized 
arctangent 
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Table 2-1. Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


ATAN2 


AT AN 2 
ATAN2V 


ATAN2 


ATAN2% 
%ATAN2% 


%ATAN2 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Computes 2— argument 
arctangent 
Computes vectorized 
2-argument arctangent 


ATS 


TM 






$ATS 




$SYSLIB 


Dep. 


Allocates table space 


AXPY 


CAXPY 
SAXPY 
SPAXPY 


CAXPY 

SAXPY 
SPAXPY 






S 

S 
S 


$SCILIB 

$SCILIB 
$SCILIB 


Ind. 
Ind. 
Ind. 


Computes y=ax+y on 
complex arrays x and y 
Computes y-ax+y on 
real arrays x and y 
Computes y=ax+y on real 
arrays x and y when y is 
referenced indirectly 


BACKSPACE 


BKFILE 
BKSP 


BACKFILE 




$BACK 

$BKSP 
$BKSPF 


s 


<fc TAT TO 

$SYSLIB 
$SYSLIB 
SSYSLIB 


Dep. 
Dep. 
Dep. 
Dep. 


bacK spaces one recoro 
Backspaces one file 
Backspaces one record 
Backspaces one file 
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Table 2-1 • Subprogram summary (continued) 







Entry Type 










Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


BICON 


BICONV 
BICONZ 


BICONV 
BICONZ 






S 
S 


$UTLIB 
$UTLIB 


Ind. 
Ind. 


Converts integer to ASCII 
character 


BTD 


BTD 


BTD 
BTD 

BTDR 

BTDL 


BTD% 


$BTD 
BTD% 

BTDR% 

BTDL% 


SF 
SF 

SF 

SF 


$UTLIB 
$UTLIB 

$UTLIB 

$UTLIB 


Ind. 
ind. 

Ind. 

Ind. 


Converts binary number to 
ASCII decimal 

Converts binary to decimal 
ASCII right justified, 
blank filled. 

Converts binary to decimal 
ASCII right justified, zero 
filled. 

Converts binary to decimal 
ASCII left justified, zero 
filled. 


BTO 


BTO 


BTO 
BTO 


BTO% 


$BTO 
BTO% 


SF 
SF 


$UTLIB 
$UTLIB 


Ind. 
Ind. 


Converts binary number to 
ASCII octal 

Converts binary to octal 
ASCII right justified, 
blank filled. 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


BTO 

continued 




BTOR 
BTOL 




BTOR% 
BTOL% 


SF 
SF 


$UTLIB 
$UTLIB 


Ind. 
Ind. 


Converts binary to octal 
ASCII right justified, zero 
filled. 

Converts binary to octal 
ASCII left justified, zero 
filled. 


CABS 


CABSV 


CABS 


CABS* 
%CABS% 


%CABS 


or 
VF 


$ARLIB 


ma, 
Ind, 


Calculates complex absolute 
value 

Calculates vectorized 
complex absolute value 


ccos 


CCOS 
CCOSV 


CCOS 


CCOS% 
%CCOS% 


%CCOS 


SF 
VF 


$ARLIB 
$ARLIB 


Ind, 
Ind, 


Computes complex cosine 
Computes vectorized complex 
cosine 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call Prom 
CAL Only 


Address 


Value 


CDC 


CDCI 
CDCO 






$CDCI 
$CDCO 




$IOLIB 
$IOLIB 


Dep. 
Dep. 


Translates CDC formatted 
input data 

Translates CDC formatted 
output data 


CEXPR 


CEF 


CEXPR 






S 


$SYSLIB 


Ind. 


Transforms an expression 
character string to a 
Reverse Polish Table 


CHAR 




















CARCON 






$MOVE 




$FTLIB 


Ind. 


Transfers one character 


















item to result 










$FAD 




$FTLIB 


Ind. 


Terminates transfer 




OCARCON 






$CCI 




$FTLIB 


Ind. 


Initializes concatenation 


















for store 










$CCT 




$FTLIB 


Ind. 


Transfers one character 


















item to result 










$CCF 




$FTLIB 


Ind. 


Terminates transfer 




CHARCPR 


LGE 




$GE 


SF 


$FTLIB 


Ind. 


Compares ASCII arguments 


















for greater than or equal to 






LGT 




$GT 


SF 


$FTLIB 


Ind. 


Compares ASCII arguments 


















for greater than 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


CHAR 

continued 


INDJbA 
LEN 


LLT 
LLE 

INDEX 
LEN 




$LT 
$LE 
$EQ 
$NE 


SF 
SF 

©J? 
SF 


$PTLIB 
$PTLIB 
$PTLIB 
$FTLIB 
iiiXU 

$FTLIB 


Ind. 
Ind. 
Ind. 
Ind. 

ind . 

Ind. 


Compares ASCII arguments 
for less than 
Compares ASCII arguments 
for less than or equal to 
Compares ASCII arguments 
for equality 

Compares ASCII arguments 

for nonequality 

Finds position or second 

argument as substring of 

first argument 

Finds length of argument 


CHCONV 


CHCONV 


CHCONV 






S 


$UTLIB 


Ind, 


Converts ASCII character to 
integer 


CLEARBT 


BTMODE 


CLEARBT 






S 


$UTLIB 


Dep. 


Temporarily disables 
bidirectional memory 
transfers 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
cal only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


CLEARBTS 


BTMODE 


CLEARBTS 






S 


$UTLIB 


Dep. 


Permanently disables 
bidirectional memory 
transfers 


CLEARFI 


F I MODE 


CLEARFI 






S 


$UTLIB 


Dep. 


Temporarily prohibits 
floating-point interrupts 


CLEARFIS 


FIMODE 


CLEARFIS 






S 


$UTLIB 


Dep. 


Permanently prohibits 
floating-point interrupts 


CLOCK 


CLOCK 


CLOCK 






S/SF 


$UTLIB 


Dep. 


Supplies current system 
clock in hhimmiss format 


CLOSE 


CLOSE 
SYMDBC 


CLOSE 
CLOSE 




$CLS 


SA 
S 


$IOLIB 
$SYSLIB 


Dep. 
Dep. 


Terminates the connection 
of a dataset to a unit 
Closes a random, unblocked 
dataset 



SR-0014 



2-13 



I 



Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CPT Standard 


CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


CMPLX 


REAL 


CMPLX 






SP 


$ARLIB 


Ind. 


Converts two reals to 
complex 


COMPL 


BOOLEAN 


COMPL 






SP 


$ARLIB 


Ind. 


Forms logical complement 


CONJG 


COMPLX 


CONJG 






SP 


$ARLIB 


Ind. 


Computes complex conjugate 


COPY 


ccopy 
scopy 


CCOPY 
SCOPY 






s 
s 


$SCILIB 
$SCILIB 


Ind. 
Ind. 


Copies complex array into 
complex array 

Copies real array into real 
array 


COPYD 


copy 


COPYD 






s 


$IOLIB 


Dep. 


Copies one dataset to 
another; EOD not copied 
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Table 2-1. Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


COPYP 


copy 


COPYF 






S 


$I0LIB 


Dep. 


Copies files from one 
dataset to another; EOD not 
written 


COPYR 


COPY 








S 


$I0LIB 


Dep. 


Copies records from one 
dataset to another; EOF not 
written 


COPYU 


COPYU 


COPYU 






S 


$IOLIB 


Dep, 


Copies data to EOD in 
unblocked format 


COS 


COS 
COSV 


COS 


cos% 
%COS% 


%COS 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Computes cosine 

Computes vectorized cosine 


COSH 


COSH 
COSHV 


COSH 


COSH% 
%COSH% 


%COSH 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Computes hyperbolic cosine 
Computes vectorized 
hyperbolic cosine 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CPT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


COSS 


COSS 

cossv 


COSS 




COSS% 
%COSS 

%COSS% 


or 
VF 

VF 


$ARLIB 
$ARLIB 


xna. 
Ind. 

Ind. 


Computes cosine and sine 
Computes vectorized cosine 
and sine 
Same as %COSS 


COSSH 


COSH 

COSHV 

COSHV 


COSSH 




COSSH% 
%COSSH 


SF 
VF 
VF 


$ARLIB 
$ARLIB 
$ARLIB 


Ind. 
Ind. 
Ind. 


Computes hyperbolic cosine 
and sine 

Computes vector i2ed 
hyperbolic cosine and sine 
Same as %COSSH 


COT 


COT 
COTV 


COT 


COT% 
%COT% 


%COT 


SF 
VF 


$ARLIB 
3ARLIB 


Ind. 
Ind. 


Computes cotangent 
Computes vectorized 
cotangent 


CRACK 




CRACK 






c 
o 




Dep. 


Kerormacs a user— supp±iea 
string into verb, 
separators, keywords and 
values 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call Prom 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


CS 


CCS 


CCS 




$CS 
$CCS 


S 
S 


$SYSLIB 
$SYSLIB 


Dep. 
Dep. 


Cracks control statement 
Cracks control statement 


CSIN 


CSIN 
CSINV 


CSIN 


CSIN% 
%CSIN% 


%CSIN 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Computes complex sine 
Computes vectorized complex 
sine 


CTOC 


CTOCSS 
CTOCSV 
CTOCVS 
CTOCW 




CTOC% 
CTO%C% 
%CTOC% 
%CTO%C% 




SF 
VF 
VF 
VF 


$ARLIB 
$ARLIB 
$ARLIB 
$ARLIB 


Ind. 
Ind. 
Ind. 
Ind. 


Raises complex scalar to 
complex scalar power 
Raises complex scalar to 
complex vector power 
Raises complex vector to 
complex scalar power 
Raises complex vector to 
complex vector power 


CTOI 


CTOISS 
CTOISV 




CTOI% 
CTO%I% 




SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Raises complex scalar to 
integer scalar power 
Raises complex scalar to 
integer vector power 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Pr imary 
Reference 
Name 


UPDATE 

Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


CTOI 

continued 


CTOIVS 
CTOIW 




%CTOI% 
%CTO%I% 




VF 
VF 


$ARLIB 
$ARLIB 


Xnd. 
Ind. 


Raises complex vector to 
integer scalar power 
Raises complex vector to 
integer vector power 


CTOR 


CTORSS 
CTORSV 
CTORVS 
CTORW 




CTOR% 
CTO%R% 

%CTO%R% 




SF 
VF 
VF 
VF 


$ARLIB 
$ARLIB 
$ARLIB 
$ARLIB 


Ind. 
Ind. 
Ind. 
Ind, 


Raises complex scalar to 
real scalar power 
Raises complex scalar to 
real vector power 
Raises complex vector to 
real scalar power 
Raises complex vector to 
real vector power 


DABS 


DBLE 


DABS 






SA 


$ARLIB 


Ind, 


Determines double-precision 
absolute value 


DATAN 


DATAN 
DATANV 


DATAN 


DATAN% 
%DATAN% 


% DATAN 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Computes double-precision 
arctangent 
Computes vectorized 
double-precision arctangent 
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Table 2-1 « Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


DAT AN 2 


DATAN 
DATANV 


DATAN2 


DATAN 2% 
%DATAN2% 


%DATAN2 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Computes double-precision 
2-araument arctanaent 
Computes vectorized 
double-precision 2-argument 
arctangent 


DATETIME 


DATE 

JDATE 

TIMEF 


DATE 

JDATE 

TIMET 






S/SF 
S/SF 
SF 


$UTLIB 
$UTLIB 
$UTLIB 


Dep. 
Dep« 
Dep, 


Returns current date in 

mmiddxyy format 

Returns current Julian date 

in yyddd format 

Returns time since initial 

TIMEF call in milliseconds 


DBLE 


REAL 


DBLE 






SF 


$ARLIB 


Ind. 


Converts type real to 
double precision 


DCOS 


DCOS 
DCOSV 


DCOS 


DCOS% 
%DCOS% 


%DCOS 


SF 
VF 


Aarltb 
$ARLIB 


Ind 

Ind. 


vVUI^U LCO UUUU^C r*" **** Jm\Jl 1 

cosine 

Computes vectorized 
double-precision cosine 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


DDIM 


DDIM 
DDIMV 


DDIM 


DDIM% 
%DDIM% 


%DDIM 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Double-precision positive 
real difference 


DECODE 


RFD 






$DFI 

$DFV $DFA 

rf» T"> TTtX TO. 

ffDFV% 
$DFF 




$IOLIB 
$IOLIB 

$IOLIB 


Dep* 
Dep. 

Dep. 


Initializes for decode 
Cracks format; decodes 
input. 

Terminates decode 


DELETE 


DELETE 


DELETE 






S 


$SYSLIB 


Dep. 


Removes a saved dataset 
from the Dataset Catalog 


DELTSK 


DELTSK 






$DELTSK% 




$UTLIB 


Ind. 


Deletes calling task 


DIM 


REAL 


DIM 






SF 


$ARLIB 


Ind. 


Computes positive real 
difference 
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Table 2-1. Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


DINT 


DINT 
DINTV 


DINT 






SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Truncates double-precision 
numbers to integers 


DISPOSE 


DISPOSE 


DISPOSE 






S 


$SYSLIB 


Dep. 


Directs a dataset to the 
specified queue 


DMOD 


DMOD 


DMOD 


DMOD% 
%DMOD 


%DMOD 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Computes division remainder 


DNINT 


DNINT 
DNINTV 


DNINT 


DNINT% 
%DNINT% 


%DNINT 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Calculates nearest integer 


DOT 


CDOT 


CDOTC 
CDOTU 






SF 
SF 


$SCILIB 
$SCILIB 


Ind. 
Ind. 


Finds the conjugated dot 
product of two complex 

Finds the unconjugated dot 
product of two complex 
arrays 
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Table 2-1, Subprogram summary (continued) 







Entry Type 










Pr imary 


UPDATE 


CPT Standard 




CFT 








Reference 


Deck 






Call From 


Call 


Library 


OS 


Purpose 


Name 


Name 


Address 


Value 


CAL Only 


Type 


Dep 


DOT 


SDOT 


SDOT 






SF 


$SCILIB 


Ind. 


Finds the dot product of 


continued 
















two real arrays 




SPDOT 


SPDOT 






SF 


$SCILIB 


Ind. 


Finds the dot product of 
two real arrays; one array 
is referenced indirectly. 


DPREC 




















DASS 




DASS% 




SF 


$ARLIB 


Ind. 


Performs double-precision 
addition 




DDSS 




DDSS% 




SF 


$ARLIB 


Ind. 


Performs double-precision 
division 




DMSS 




DMSS% 




SF 


3ARLIB 


Ind. 


Performs double-precision 
multiplication 




DSSS 




DSSS% 




SF 


$ARLIB 


Ind. 


Performs double-precision 
subtraction 




DAW 




DASV% 




VF 


$ARLIB 


Ind. 


Performs double-precision 
addition , scalar +vector 








DAVS% 




VF 


$ARLIB 


Ind. 


Performs double-precision 
addition , vector+scalar 








DAW% 




VF 


$ARLIB 


Ind. 


Performs double-precision 
addition, vector +vec tor 








DDSV% 




VF 


$ARLIB 


Ind. 


Performs double-precision 
division/ scalar/vector 




DDW 




DDVS% 




VF 


$AHLIB 


Ind. 


Performs double-precision 
division , vector /scalar 








DDW% 




VP 


$ARLIB 


Ind. 


Performs double-precision 
division, vector /vector 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


DPREC 
continued 


DVW 
DSW 




DMSV% 

DMVS% 

DMW% 

DSSV% 
DSVS% 
DSW% 




VF 

VF 

VF 

VF 
VF 
VF 


$ARLIB 

$ARLIB 

$ARLIB 

$ARLIB 
$ARLIB 
$ARLIB 


Ind. 

Ind. 

Ind. 

Ind. 
Ind. 
Ind. 


Performs double-precision 
multiplication, scalar x 
vector 

Performs double-precision 
multiplication, vector x 
scalar 

Performs double-precision 
multiplication, vector x 
vector 

Performs double-precision 
subtraction, scalar-vector 
Performs double-precision 
subtraction, vector-scalar 
Performs double-precision 
subtraction, vector -vector 


DPROD 


DBLE 


DPROD 






SA 


$ARLIB 


Ind. 


Performs double-precision 
product of two real 
arguments 


DRIVER 


DRIVER 


DRIVER 




S 


$SYSLIB 




Dep. 


Allows a user to directly 
program a CRAY channel on 
an IOS 
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Table 2-1. Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


DSASC 


DSASC 


DSASC 






S 


$UTLIB 


Ind. 


Converts display code 
character to ASCII character 


DSIGN 


DBLE 




DSIGN 




SA 


$AHLIB 


Ind. 


Transfers sign from one 
double-precision number to 
anothe r 


DSIN 


DCOS 
DCOSV 


DSIN 


DSIN% 
%DSIN% 


%DSIN 


SF 
VF 


$ARLIB 
$ARLIB 


Ind* 
Ind. 


Cottidii Hr>iihl p*-r>r<^r' t cs i cvr\ 

sine 

Computes vectorized 
double-precision sine 


DSNDSP 


DSNDSP 






$DSNDSP 




$SYSLIB 


Dep. 


Searches Logical File Table 
(LFT) in user's I/O area 
for dataset name 


DTB 


DTB 


DTB 


DTB% 


$DTB 


SF 


$UTLIB 


Ind. 


Converts ASCII decimal 
integer number to binary 
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Table 2-1. Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


DTOD 


DTODSS 
DTODSV 
DTODVS 
DTODW 




DTOD% 
DTO%D% 
%DTOD% 
%DTO%D% 




SF 
VF 
VF 
VF 


$ARLIB 
$ARLIB 
$ARLIB 
$ARLIB 


Ind. 
Ind. 
Ind, 
Ind. 


Raises double-precision 

scalar to double-precision 

scalar power 

Raises double-precision 

scalar to double-precision 

vector power 

Raises double-precision 

vector to double -precis ion 

e/19 lar nnvA r 

Raises double-precision 
vector to double -precis ion 
vector power 


DTOI 


DTOISS 
DTOISV 




DTOI% 
DTO%I% 




SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Raises double-precision 
scalar to integer scalar 

puwc J. 

Raises double-precision 
scalar to integer vector 
power 
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Table 2-1. Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


DTOI 

continued 


DTOIVS 
DTOIW 




%DTOI% 
%DTO%I% 




VF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Raises double-precision 
vector to integer scalar 
power 

Raises double-precision 
vector to integer vector 
power 


DTOR 


DTODSS 
DTODSV 
UIaJUVo 

TVTVMVT7T7 




DTOR% 

%DTOR% 
%DTO%R% 




SF 
VF 
VF 
VF 


$ARLIB 
SARLIB 


Ind. 
Ind. 

ina« 

T_ J 

Ind • 


Raises double-precision 
scalar to real scalar power 
Raises double-precision 
scalar to real vector power 
Raises double— precision 
vector to real scalar power 
Raises double— precision 

V€vuUi W Leal VcwWUi pdWeiT 


DUMP 




















TRAYDUMP 


CRAYDUMP 






c 






Print's a mpmnrv Humn to a 


















specified dataset 




PDUMP 


DUMP 




$DUMP 


s 


$UTLIB 


Dep. 


Dumps memory and aborts job 




PDUMP 


PDUMP 




$PDUMP 


s 


$UTLIB 


Dep. 


Dumps memory 
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Table 2-1 • Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


DUMPJOB 


DUMPJOB 


DUMPJOB 








$SYSLIB 


Dep. 


Creates an unblocked 
dataset containing the user 
job area image 


ECHO 


ECHO 


ECHO 






S 


$SYSLIB 


Dep. 


Allows user to turn on and 
off classes of messages to 
user logfile 


EISPACK 










S 


$ SCI LIB 


Ind. 


See table 4-4. 


ENCODE 


WPD 
WFD 

WFD 






$EPI 

$EFV $EFV% 

$EFA 

$EFF 




$IOLIB 
$IOLIB 

$IOLIB 


Dep. 
Dep. 

Dep. 


Initializes for encode 
Cracks format; encodes 
output. 

Finalizes encode 


END 


END 




$END 
END$ 




S 


$UTLIB 


Ind. 


Terminates current job step 
and advances job to next 
job step 



SR-0014 



2-27 



I 



Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 

Deck 
Name 


Entry Type 


CFT 

Call 
Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


END FILE 


EODW 
EOFR 
EOFW 






$EODW 
$EOFR 
$EOFW 


S 


$SYSLIB 
$SYSLIB 
$IOLIB 


Dep. 
Dep. 
Dep. 


Writes EOD, also EOF and 
EOR if necessary; clears 
UEOF flag in DSP. 
Detects EOF on last I/O 
operation; clears UEOF flag 

in Ubr. 

Writes EOF, also EOR if 
necessary; clears UEOF flag 
in DSP. 


ENDRPV 


RPV 


ENDRPV 




$ ENDRPV 


s 


$SYSLIB 


Dep. 


Continues normal exit 
processing after a 
reprievable request has 
been processed 




EOADF 






$EOATEST 




$SYSLIB 


Dep. 


Checks for a read/write 
past the allocated area 
condition 
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Table 2-1. Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


EOF 


I EOF 
IEOF 


EOF 
IEOF 




$IEOF 


SF 

SF 


$IOLIB 


Dep. 


Returns EOF status; clears 
UEOF in DSP. 


EQV 


BOOLEAN 


EQV 






SF 


$ARLIB 


Ind. 


Computes logical equivalence 


ERREXIT 


ABORT 


ERREXIT 






S 


$UTLIB 


Ind. 


Aborts current job step 


EVASGN 


EVASGN 


EVASGN 






S 


$UTLIB 


Ind. 


Identifies event 


EVCLEAR 


EVCLEAR 


EVCLEAR 






S 


$UTLIB 


Ind. 


Clears event 


EVPOST 


EVPOST 


EVPOST 






S 


$UTLIB 


Ind. 


Posts an event 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Audi ess 


Value 


EVREL 


EVREL 


EVREL 




S 


$UTLIB 


Ind. 


Releases event identifier 


EVTEST 


EVTEST 


EVTEST 






S 


$UTLIB 


Ind. 


Tests event for posted state 


EVWAIT 


EVWAIT 


EVWAIT 






S 


$UTLIB 


Ind. 


Delays calling task until 
event is posted 


EXCHANGE 


AJrrMi 

PXPF 

XPFMT 


XPPMT 

PXP 

B20CT 




J>r Ar 


S 
S 

s 


$SYSLIB 
3SYSLIB 
$SYSLIB 


Ind. 
Dep. 
Dep. 


Format Exchange Package 
Print Exchange Package 
Format octal representation 
of Exchange Package 


EXIT 


EXIT 


EXIT 






s 


$UTLIB 


Ind. 


Terminates current job step 
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Table 2-1, Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


EXP 


CEXP 
CEXPV 

DEXP 

DEXPV 

EXP 
EXPV 


CEXP 
DEXP 

EXP 


CEXP% 

AIT 

DEXP% 

%DEXP% 

EXP% 


%CEXP 

%DEXP 
%EXP 


SF 
VF 

SF 

VF 

SF 
VF 


$ARLIB 
$ARLIB 

$ARLIB 

$ARLIB 

9ARLIB 
$ARLIB 


Ind. 
Ind. 

Ind. 

Ind. 

Ind. 
Ind. 


Computes complex exponential 
Computes vector complex 
exponential 

Computes double-precision 
exponential 

Computes vector double- 
precision exponential 
Calculates exponential 
Calculates vector 
exponential 


FETCH 


r CiiVn 


FETCH 






S 




Dep. 


Obtains a front— end 
resident dataset and makes 
it local to a job on a Cray 
computer 


LI LW 1 1 

f ri 




















CRFFT2 


CRFFT2 






S 


$SCILIB 


Ind. 


Computes a Fast Fourier 




CFFT2 


CFFT2 






S 


$SCILIB 


Ind. 


Transform 




RCFFT2 


RCFFT2 






s 


$SCILIB 


Ind. 





SR-0014 



2-31 



I 



Table 2-1 . Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


PP6064 


FP6064 


FP6064 






S 


$UTLIB 


Ind. 


Converts CDC 
single-precision to Cray 
single-precision 


FP6460 


FP6460 


FP6460 






S 


$UTLIB 


Ind. 


Converts Cray 
single-precision to CDC 
s ingle-pr ec is ion 


FILTER 


FILTERG 
FILTERS 
OPFILT 


FILTERG 
FILTERS 
OPFILT 






S 
S 
S 


$SCILIB 
$SCILIB 
$SCILIB 


Ind. 
Ind* 
Ind. 


Calculates general filter 
coefficients 

Calculates symmetric filter 

coefficients 

Solves equations by the 

Weiner-Levinson method 


FINDCH 


FINDCH 


FINDCH 






s 


$UTLIB 


Ind. 


Searches for the occurrence 
of a specified character 
string. 
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Table 2-1 • Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


FLOAT 


INTEGER 








SF 


$ARLIB 


Ind. 


Converts type integer to 
real 


FTERP 


FTERP 




FTERP 






S5FTLIB 


Dep. 


Processes $FTLIB errors 


FLOWTRACE 




















FLOW 


TV T>/~«T>T TfclA 

ARGfLIMQ 






s 


$UTLIB 


Ind. 


Controls argument printing 


















for flowtrace 




FLOW 








s 


$UTLIB 


Ind, 


Processes CFT flowtrace 


















option for calls 




FIajW 


FIjOWEXIT 






s 


JUTLIB 


T J 

Ind* 


Processes CFT flowtrace 


















option for RETURN statements 




JTlAJri 


FLOWLIM 






Q 


TTTTTT TTA 
t}UlLtJ.D 


j. no, • 


octs iiiuii on une numoer or 


















subroutine caj.±s to oe 


















traced 






FLOWSTOP 






<3 

w 




xriQ » 




















option 




FLOW 


SETPLIMQ 






s 


$UTLIB 


Ind,. 


Controls CALL printing for 


















flowtrace 
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Table 2*-l. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


FOLR 


FOLR 


FOLR 






S 


$SCILIB 


Ind« 


Solves first-order linear 
recurrences 


FOLRN 


FOLRN 


FOLRN 






S 


$SCILIB 


Ind. 


Solves for the last term of 
a first-order linear 
recurrence 


FOLRP 


FOLRP 


FOLRP 






S 


$SCILIB 


Ind. 


Solves first-order linear 
recurrences 


FOLR2 


FOLR2 


FOLR2 






S 


$SCILIB 


Ind* 


Solves first-order linear 
recurrences 


P0LR2P 


FOLR2P 


FOLR2P 






S 


$SCILIB 


Ind, 


Combination of FOLRP & FOLR2 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CPT Star 
Address 


idard 
Value 


Call From 
CAL Only 


GATHER 


GATHER 


GATHER 






S 


$SCILIB 


Ind. 


Gathers a vector from a 
source vector 


GETB1 


SYMDBC 


GETB1 






SF 


$SYSLIB 


Dep. 


Returns address of 
subroutine name 


GETDSP 


GTDSP 


GETDSP 




$GTDSP 
$GTDSP% 


SF 


$SYSLIB 


Dep. 


Locates a Dataset Parameter 
Table 


GETLPP 


GLPP 


GETLPP 






SF 


$SYSLIB 


Dep. 


Returns lines from JCLPP 


GETNAMEQ 


GNAMEQ 


GETNAMEQ 






S 


$UTLIB 


Dep. 


Returns ASCII 
left-justified, 
space -filled name of 
routine that called 
FLOWENTR or FLOWEXIT 
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Table 2-1 . Subprogram summary (continued) 



Pr iraary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CPT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call Prom 
k*ali unj.y 


Address 


Value 


GETPOS 


GETPOS 

GPOS 

GTPOS 


GETPOS 


$GPOS 
GTPOS % 




SF 


$IOLIB 

$SYSLIB 

$SYSLIB 


Dep. 
Dep* 
Dep, 


Gets dataset position 
Gets tape dataset position 


GETREGS 


GNAMEQ 


GETREGS 






S 


$UTLIB 


Ind. 


Returns register usage 
statistics for FLOWENTR 


GPARAM 


GPARAM 


GETPARAM 




$GP 

&GPARAM 
$PAL 


S 


$SYSLIB 

$SYSLIB 
$SYSLIB 


Dep. 

Dep. 
Dep. 


All three routines transfer 
control statement parameter 
values to an array provided 
by the calling routine 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 

H i ii i ii ii 


Entry Type 


CFT 

Call 

Tvoe 


Librarv 


OS 
Dep 




CFT Standard 


Call From 
CAL Only 


Address 


Value 


HEAP 


















MANAGER 


HP ALLOC 


HPALLOC 




ALLOC% 


s 


SSUTLIB 


Dep. 


Allocates a block of memorv 


















from the heap 




HPCHECK 


HPCHECK 




HCHECK% 


s 


&UTLIB 


Den* 


Checks intearitv of the heao 




HPCLMOVE 


HPCLMOVE 




CLMOVE% 


s 


S5UTLIB 


Deo. 


Ph^napR 1enai"h of ^ hppn 


















hlock • and moves block if 




































place 




HPDEALLC 


HPDEALLC 




DEALLC% 


s 


$UTLIB 


Dep. 


Returns a block of memory 


















to the heap 




HPDUMP 


HPDUMP 




HPDUMP% 


s 


$UTLIB 


Dep. 


Writes information about 


















the heap to a dataset 




HPGROW 






HPGROW% 




$UTLIB 


Dep. 


Heap expansion routine 




HPLEN 


I HPLEN 




HPLEN% 


SF 


$UTLIB 


Dep. 


Returns length of a heap 


















block 




HPMEM 






HPMEM% 




$UTLIB 




Mentor v reouest routine 




HPMERGE 






HMERGE% 




S5UTLIB 








HPNEWLEN 


HPNEWLEN 




NEWLEN% 


c 
o 


<fcTFPT T"R 




Lnanyes leng un or a neap 


















block 




HPSHRINK 


HPSHRINK 




SHRINK% 


s 


$UTLIB 


Dep. 


Returns memory from heap to 


















operating system 




HPSTAT 


IHPSTAT 




HPSTAT% 


SP 


$UTLIB 


Dep. 


Returns information about 


















the heap 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


I00DEL 


I00DEL 


IOODEL 






SF 


$UTLIB 


Ind* 


Deletes SKOL string or 
substring and returns the 
length of resulting string 


I00ERR 


IOOERR 


IOOERR 






S 


$UTLIB 


Ind. 


Handles run time errors in 
SKOL programs 


I00MVC 


I00MVC 


IOOMVC 






SF 


$UTLIB 


Ind. 


Replaces SKOL string or 
substring with simple 
character and returns the 
length of resulting string 


I00MVM 


I00MVM 


I00MVM 






SF 


$UTLIB 


Ind. 


Replaces SKOL string or 
substring with another SKOL 
string or substring and 
returns the length of the 
resulting string 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


I00ORD 


I00ORD 


I00ORD 






SF 


$UTLIB 


Ind. 


Returns internal SKOL code 
for a given ASCII character 


10 OREAD 


I00READ 


I00READ 






S 


$UTLIB 


Ind. 


Reads a logical record in 
Al format and converts each 
word containing an ASCII 
character , left-justif led, 
space-filled, to its 
internal SKOL code 


I00SETUP 


I00SETUP 


I00SETUP 






s 


$UTLIB 


Ind* 


Initializes a SKOL 
program's table for direct 
translation of ASCII 
character codes to internal 
ordinal numbers 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 

Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


IOOWRITE 


IOOWRITE 


IOOWRITE 






S 


$UTLIB 


ind. 


Writes characters defined 
by TYPE CHAR statement; 
converts character ordinals 
to ASCII characters in (Al) 
format, left-justif led, 
space-filled , and then 
writes them as a logical 
record. 


IABS 


INTEGER 


IABS 






SF 


$ARLIB 


Ind. 


Computes integer absolute 
value 


IBM 


IBMI 
IBMO 






$IBMI 
$IBMO 




$IOLIB 
$IOLIB 


Dep* 
Dep. 


Translates input IBM 
formatted data 
Translates output IBM 
formatted data 


AwU*Lr\A 


ICAMAX 


ICAMAX 






SF 


$SCILIB 


Ind. 


Finds the first index of 
the maximum absolute value 
of a complex array 
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Table 2-1. Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


ICEIL 


ICEIL 


ICEIL 






SF 


SUTLIB 


Ind # 


Returns int^oAr ceilino of 
a rational number 
represented as two integer 
parameters 


IDIM 


INTEGER 


IDIM 






SF 


$ARLIB 


Ind, 


Computes positive integer 
difference 


IDNINT 


IDNINT 


IDNINT 


IDNINT% 
% IDNINT 


%IDNINT% 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Finds nearest integer to 
double-precision number 


IFDNT 


IFDNT 


IFDNT 






SF 


$SYSLIB 


Dep. 


Determines if a dataset is 
local to the job 


IGTBYT 


IGTBYT 


IGTBYT 






SF 


$UTLIB 


Ind. 


Fetches bytes 
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Table 2-1 • Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CPT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CPT Standard 


Call Prom 
CAL Only 


Address 


Value 


IILZ 


IILZ 


IILZ 








$SCILIB 


Ind. 


Returns the number of zero 
values before the first 
nonzero value 


UN 


NCON 






$IIN 




$UTLIB 


Ind. 


Contains integer powers of 
10 in range of 10° to 
1018 


ILLZ 


ILLZ 


ILLZ 






SF 


$SCILIB 


Ind. 


Returns the number of 
values that do not have the 
first bit set before the 
first value that does have 
the first bit set 


ILSUM 


ILSUM 


ILSUM 






SF 


$SCILIB 


Ind. 


Returns total number of 
true values in array 
declared LOGICAL 
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Table 2-1 . Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


XMX 


NCON 






$IMX 




$UTLIB 


Ind. 


Contains double-precision 
floating-point 
representation of negative 
powers of 10 in range of 
100 to 10-4096 


INQUIRE 


INQUIRE 


INQUIRE 




$INQ 


SA 


$IOLIB 


Dep. 


Returns the status of a 
unit or a dataset 


I No ASCI 


INSASCI 




INSASCI% 




S 


$SYSLIB 


Ind, 


Inserts ASCII parameters 
into a message 


INT 


REAL 


INT 







SF 


$ARLIB 


Ind. 


Truncates to integer value 


INT 


TM 






$INT 




$SYSLIR 


Dep. 


Initializes table pointers 
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Table 2-1 • Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CPT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call Prom 
CAL Only 


Address 


Value 


INT6064 


1NT6064 


INT6064 






S 


$UTLIB 


Ind. 


Converts CDC integer to 
Cray integer 


INT6460 


INT6460 


INT6460 






S 


$UTLIB 


Ind. 


Converts Cray integer to 
CDC integer 


IOERP 


IOERP 






IOERP% 
NLERP% 




$IOLIB 
$IOLIB 


Dep. 
Dep. 


Processes I/O errors 
Processes NAMELIST errors 


IOSTAT 


IOSTAT 


IOSTAT 






SF 


$IOLIB 


Dep. 


Returns EOF status; clears 
UEOF in DSP. 


IPX 


NCON 






$IPX 




$UTLIB 


Ind. 


Contains double-precision 
floating-point 
representation of positive 
powers of 10 in range of 
100 to 10-4096 
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Table 2-1 • Subprogram summary (continued) 







Entry Type 










Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


ISAMAX 


ISAMAX 


ISAMAX 






SF 


$SCILIB 


Ind. 


Finds the first index of 
the largest absolute value 
in a real array 


ISAMIN 


ISAMIN 








SF 


$SCILIB 


Ind* 


Finds first index of the 
smallest absolute value in 
a real vector 


ISIGN 


INTEGER 


ISIGN 






SF 


$ARLIB 


Ind, 


Transfers sign from one 
integer to another 


ISRCH 


ISRCHEQ 
ISRCHNE 
ISRCHFLT 
ISRCHFLE 

ISRCHFGE 
ISRCHILT 


ISEARCH 

ISRCHEQ 

ISRCHNE 

ISRCHFLT 

ISRCHFLE 

ISRCHFGT 

ISRCHFGE 

ISRCHILT 






SF 


$SCILIB 


Ind. 


Returns the first location 
of a true condition 
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Table 2-1 • Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


ISRCH 
continued 


ISRCHILE 
ISRCHIGT 
ISRCHIGE 


ISRCHILE 
ISRCHIGT 
ISRCHIGE 














ISMAX 


ISMAX 


ISMAX 






SF 


$SCILIB 


Ind. 


Finds the first index of 
the maximum of an array 


ISMIN 


ISMIN 


ISMIN 






SF 


$SCILIB 


Ind. 


Finds the first index of 
the minimum of an array 


ITOI 


ITOISS 
ITOIVS 
ITOIW 




ITOI% 
%ITOI% 
ITO%I% 
%ITO%I% 




SF 
VF 
VF 
VF 


$ARLIB 
$ARLIB 
$ARLIB 
$ARLIB 


Ind. 
Ind. 
Ind. 
Ind. 


Raises integer scalar to 
integer scalar power 
Raises integer vector to 
integer scalar power 
Raises integer scalar to 
integer vector power 
Raises integer vector to 
integer vector power 
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Table 2-1 ♦ Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


JNAME 


JNAME 


JNAME 






SF 


$SYSLIB 


Dep. 


Returns job name 


KOMSTR 


KOMSTR 


KOMSTR 






SF 


$UTLIB 


Ind. 


Compares bytes 


LEAD ZERO 


BOOLEAN 


LEADZ 






SF 


$ARLIB 


Ind. 


Tallies number of leading 
zero bits 


LENGTH 


LENGTH 


LENGTH 






SF 


$IOLIB 


Dep. 


Returns number of words 
processed in last BUFFER 
I/O operation 


LINPACK 










S 


$SCILIB 


Ind. 


See table 4-3. 
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Table 2-1 • Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address Value 


LGO 




LGO 


$LGO 


c 




Dep. 


Loads an absolute program 
from a local dataset 
containing the binary image 
as the first record 


LOADF 


LOADF 




$STOREF 

$LOADI 

$LOADR 
$LOADL 

$LOADC 




$UTLIB 


Ind* 


Performs run time array 
bounds checking 
(Performed by all LOADF 
routines) 


LOC 


LOC 


LOC 




SF 


$FTLIB 


Ind. 


Returns first word address 
of argument 


LOCKASGN 


LOCKASGN 


LOCKASGN 




S 


$UTLIB 


Ind. 


Identifies lock 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CPT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call Prom 
CAL Only 


Address 


Value 


LOCKOFF 


LOCKOFF 


LOCKOFF 






S 


$UTLIB 


Ind. 


Clears lock 


LOCKON 


LOCKON 


LOCKON 






S 


$UTLIB 


Ind. 


Sets lock 


LOCKREL 


LOCKREL 


LOCKREL 






S 


$UTLIB 


Ind. 


Releases lock 


LOCKTEST 


LOCKTEST 


LOCKTEST 






S 


$UTLIB 


Ind. 


Tests lock 


LOG 


ALOG 
ALOGV 

ALOG10 
ALOG10V 

CLOG 
CLOGV 


ALOG 

ALOG10 

CLOG 


ALOG% 
%ALOG% 

ALOG10% 
%ALOG10% 

CLOG% 
%CLOG% 


%ALOG 

%ALOG10 

%CLOG 


SF 
VF 

SP 
VF 

SF 
VF 


$ARLIB 
$ARLIB 

$ARLIB 
$ARLIB 

$ARLIB 
$ARLIB 


Ind. 
Ind. 

Ind. 
Ind. 

Ind. 
Ind. 


Computes natural logarithm 
Computes vector natural 
logarithm 

Computes common logarithm 
Computes vector common 
logarithm 

Computes complex logarithm 
Computes vector complex 
logarithm 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


LOG 

continued 


DLOG 
DLOGV 

DLOG 
DLOGV 


DLOG 
DLOG10 


DLOG% 
%DLOG% 

DLOG10% 
%DLOG10% 


%DLOG 
%DLOG10 


SF 
VF 

SF 
VF 


$ARLIB 
$ARLIB 

$ARLIB 
$ARLIB 


Ind. 
Ind. 

Ind. 
Ind, 


Computes double-precision 
natural logarithm 
Computes vector 
double-precision natural 
logarithm 

Computes double-precision 
common logarithm 
Computes vector 
double-precision common 
logarithm 


LOGECHO 


LOGECHO 


LOGECHO 






S 


$UTLIB 


Dep. 


Writes last line formatted 
by $WFD as a message to 
SLOG file 


MASK 


BOOLEAN 


MASK 






SF 


$AKLIB 


Ind, 


Forms ones mask from left 
of argument bits if 
v<(ii*g<bj ; rorros ones masK 
from right of 
(128-arguraent) bits if 
64<arg<128. 
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Table 2-1. Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


MEM 


TM 






$MEM 




$SYSLIB 


Dep. 


Requests memory 


MEMORY 


MEM 


MEMORY 






S 


$SYSLIB 


Dep. 


Determines or changes the 
amount of memory assigned 
to a job 


MINV 


MINV 


MINV 






S 


$SCILIB 


Ind. 


Solves linear equations , 
using a partial pivot 
search and Gauss-Jordan 
reduction 


MOD 


DMOD 
DMODV 


DMOD 


DMOD% 
%DMOD% 


%DMOD 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind, 


Performs double-precision 
modulo arithmetic 
Performs vectorized 
double-precision modulo 
arithmetic 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 


UPDATE 


CFT Standard 




CFT 








Reference 


Deck 






Call Prom 


Call 


Library 


OS 


Purpose 


Name 


Name 


Address 


Value 


caij unxy 


Type 


Dep 


MOD 


















continued 


LDIW 




LDSV% 




VP 


$ARLIB 


Ind. 


Performs 64-bit integer 
division, scalar/vector 








LDVS% 




VP 


$ARLIB 


Ind. 


Performs 64-bit integer 
division, vector/scalar 








LDW% 




VP 


$ARLIB 


Ind. 


Performs 64-bit integer 
division, vector /vector 




LDMOD 




LDSS« 




SP 


$ARLIB 


Ind. 


Performs 64-bit integer 
division, scalar/scalar 






MOD 


MOD% 




SP 


$AHLIB 


Ind. 


Performs 64-bit modulo 
arithmetic on two integer 
scalars 








MODSS% 




SF 


$ARLIB 


Ind. 


Same as MOD 




MODW 




%MOD% 




VP 


$ARLIB 


Ind. 


Performs 64-bit modulo 
arithmetic on two integer 
vectors 








MODW% 




VP 


$AJRLIB 


Ind. 


Same as %MOD% 








MODSV% 




VF 


$ARLIB 


Ind. 


Performs 64-bit modulo 
arithmetic on integer 
scalar and integer vector 








MODVS* 




VP 


$ARLIB 


Ind. 


Performs 64-bit modulo 
arithmetic on integer 
vector and integer scalar 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


MODIFY 


MFY 


MODIFY 






S 


$SYSLIB 


Dep. 


Changes permanent dataset 
characteristics 


MOVBIT 


MOVBIT 


MOVBIT 






S 


$UTLIB 


Ind. 


Moves bits 


MSC 


TM 






$MSC 




$SYSLIB 


Dep. 


Searches table with mask 


MS 10 


RAIO 


OPENMS 
WRITMS 
READMS 
CLOSMS 
STINDX 
FINDMS 






s 

S 

s 

S 
S 

s 


$IOLIB 
$IOLIB 
$IOLIB 
$IOLIB 
$IOLIB 
$IOLIB 


Dep. 
Dep. 
Dep. 
Dep* 
Dep. 
Dep. 


Allows user to specify how 
records of a dataset are to 
be changed without 
limitations of sequential 
access 


MVC 


MVC 


MVC 






s 


$UTLIB 


Ind. 


Moves characters 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call Prom 
CAL Only 


Address 


Value 


MVE 


TM 






$MVE 




$SYSLIB 


Dep* 


Moves memory words to table 


MXM 


MXM 


MXM 






S 


$SCILIB 


Ind. 


Performs matrix multiply 
with fixed row and column 
spacing 


MAMA 


MXMA 


MXMA 






S 


$SCILIB 


Ind. 


Performs matrix multiply 
with arbitrary row and 
column spacing 


MXV 


MXV 


MXV 






S 


$SCILIB 


Ind, 


Performs matrix-vector 
multiply with fixed row and 
column spacing 


F1A VA 


MXVA 


MXVA 






S 


$SCILIB 


Ind* 


Performs matrix-vector 
multiply with arbrtrary row 
and column spacing 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


NACSED 


PDDED 


NACSED 






SF 


$SYSLIB 


Dep. 


Returns edition number of 
last dataset that was 
accessed, acquired, or saved 


NAMELIST 




















RNL 










$IOLIB 


Ind. 


Reads NAMELIST input 






pVTT C7TD 






S 


$IOLIB 


Ind. 


Determines action for wrong 


















NAMELIST group 






KNLTYJPr* 






s 


$IOLIB 


Ind. 


Determines action for 


















NAMELIST type mismatch 


















across equal sign 






RNLECHO 






s 


$IOLIB 


Ind. 


Specifies unit for NAMELIST 


















error messages and input 


















echo 






KNU LACi 






s 


$IOLIB 


Ind. 


Adds or removes NAMELIST 


















echo-initiating characters 






RNLDELM 






s 


$IOLIB 


Ind. 


Adds or removes NAMELIST 


















group name delimiting 


















character 






RNLSEP 






s 


$IOLIB 


Ind. 


Adds or removes NAMELIST 


















separator character 






RNLREP 






s 


$IOLIB 


Ind. 


Adds or removes NAMELIST 


















replacement character 






RNLCOMM 






s 


$IOLIB 


Ind. 


Adds or removes NAMELIST 


















trailing comment characters 
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Table 2-1* Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 




Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Address 


Value 


NAMELIST 
continued 


WNL 


WNLLONG 

WNLDELM 

WNLSEP 

WNLREP 

WNLFLAG 




$WNL 


S 
S 
S 

s 
s 


$IOLIB 
$IOLIB 

$IOLIB 

$IOLIB 

$IOLIB 

$IOLIB 


Ind. 
Ind. 

Ind. 

Ind. 

Ind. 

Ind. 


Writes NAMELIST output 
Specifies NAMELIST output 
line length 
Specifies NAMELIST 
delimiting character 
Specifies NAMELIST 
separator character 
Specifies NAMELIST 
replacement character 
Specifies first character 
of first line 


NEQV 


BOOLEAN 


NEQV 






SF 


$ARLIB 


Ind. 


Computes logical difference 


NICV 




















NICV 






NICV% 




$UTLIB 


Ind. 


Converts numeric input 










$NICV 




$UTLIB 


Ind. 






NICONV 


NICONV 






S 


$UTLIB 


Ind. 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


NINT 


INTEGER 


NINT 






SA 


$ARLIB 


Ind. 


Calculates nearest integer 


NOCV 


NOCV 
NOCONV 


NOCONV 




NOCV% 
$NOCV 


S 


$UTLIB 
$UTLIB 
$UTLIB 


Ind. 
Ind. 
Ind. 


Converts numeric output 


NORERUN 


RERUN 


NORERUN 






S 


$SYSLIB 


Dep. 


Controls monitoring of 
conditions causing job to 
be flagged as not rerunnable 


NUMBLKS 


NUMBLKS 


NUMBLKS 






S 


$SYSLIB 


Dep. 


Returns current size of 
dataset in 512-word blocks 
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Table 2-1 . Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CPT 
Call 

Type 


Library 


OS 
Dep 


Purpose 


CPT Standard 


Call From 
CAL Only 


Address 


Value 


OPEN 


SYMDBC 
OPEN 


OPEN 




$OPN 


S 

SA 


$SYSLIB 
$IOLIB 


Dep. 
Dep. 


Opens a random, unblocked 
dataset 

Connects existing dataset 
to unit, creates 
preconnected dataset, 
creates dataset and 
connects it to unit, or 
changes certain specifiers 
of connection between 
dataset and unit. 
(Implements FORTRAN OPEN 
statement.) 


OR 


BOOLEAN 


OR 






SF 


$ARLIB 


Ind. 


Forms logical sum 


ORDERS 


ORDERS 


ORDERS 






S 


$SCILIB 


Ind. 


Internally sorts 
fixed-length records 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call Prom 
CAL Onlv 


Address 


Value 


OTB 


OTB 


OTB 






SF 


$UTLIB 


Ind. 


Converts octal ASCII number 
to binary 


OVERLAY 


OVERLAY 


OVERLAY 






S 


$UTLIB 


Dep, 


Processes overlays 


P32 


P32 


P32 






S 


$UTLIB 


Ind. 


Packs 32-bit words 


P6460 


P6460 


P6460 






S 


$UTLIB 


Ind. 


Packs 60-bit words 


PACK 


PACK 


PACK 






S 


$SYSLIB 


Ind, 


Packs a specified number of 
words into a packed list 


PAUSE 


STOP 






$PAUSE 




$UTLIB 


Ind. 


Suspends program execution 
or terminates job step; 
installation dependent. 
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Table 2-1 • Subprogram summary {continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


PBN 


PBN 






$APBN 
$PBN 




$SYSLIB 
$SYSLIB 


Dep. 
Dep* 


Asynchronously postions 
dataset 

Synchronously positions 
dataset 


PERF 


PERF 


PERF 






S 


$SYSLIB 


Dep. 


Hardware performance monitor 


PERMIT 


PER 


PERMIT 






s 


$SYSLIB 


Dep. 


Allows the owner of a 
permanent dataset to 
control the manner in which 
other users can use the 
dataset 


PPL 


PPL 


PPL 






s 


$SYSLIB 


Dep. 


Processes keywords for a 
given directive 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


POPCNT 


BOOLEAN 


POPCNT 






SF 


$ARLIB 


Ind. 


Tallies number of bits set 
in a word 


POPPAR 


BOOLEAN 


POPPAR 






SF 


$ARLIB 


Ind. 


Parity of number of bits 
set in a word 


PRCW 


PRCW 






$PRCW 




$SYSLIB 


Dep. 


Positions dataset after an 
RCW 


PTS 


TM 






$PTS% 




$SYSLIB 


Dep. 


Presets table space 


PUTBYT 


PUTBYT 


PUTBYT 






S 


$UTLIB 


Ind. 


Stores byte 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


RANDOM 


RANF 
RANFV 

RANGET 

RANSET 


RANF 
RANSET 


RANF% 
%RANF% 

RANSET% 


%RANF 


SF 
VF 

SF 

S 


$ARLIB 
SARLIB 

$ARLIB 

$ARLIB 


Ind. 
Ind. 

Ind. 

Ind. 


Returns a random number 
Returns a vector of random 
numbers 

Returns current seed of the 
random number generator 
Sets random seed 


RANFI 


RANSED 






RANFI 




$ARLIB 


Ind. 


Contains current index to 
seed buffer for random 
number generator 


RANFS 


RANSED 






RANFS 




$ARLIB 


Ind* 


Contains 128 random number 
seeds in a buffer 


RB 


RB 






$RB 




$IOLIB 


Dep. 


Initiates buffered input 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


RBN 


RBN 


RBN 




$RBN 


SF 


$SYSLIB 


Ind. 


Replaces trailing blanks 
with nulls 


RCW 


RCW 






$RCHP 
$RCHR 
$RCWP 
$RCWR 




$SYSLIB 
$SYSLIB 
$SYSLIB 
$SYSLIB 


Dep. 
Dep. 
Dep. 
Dep. 


Reads characters in partial 
record mode 

Reads characters in record 
mode 

Reads words in partial 
record mode 

Reads words in record mode 


RDIN 


SYMDBC 


RDIN 






S 


$SYSLIB 


Dep. 


Reads a buffer of data from 
a random, unblocked dataset 


RDYQUE 


RDYQUE 






$RDYQUE% 




$UTLIB 


Ind. 


Readies a queue of tasks 
for execution 


RDYTSK 


RDYTSK 






$RDYTSK% 




$UTLIB 


Ind. 


Readies a task for execution 
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Table 2-1 • Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

call 
Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


V*dXX C L\Jtll 

CAL Only 


Address 


Value 


READ 


READ 


READ 






S 


$IOLIB 


Ind* 


Reads words , full record 
mode 


READC 


READC 


READC 






S 


$IOLIB 


Ind, 


Reads characters, full 
record mode 


READCP 


READCP 


READCP 






S 


$IOLIB 


Ind. 


Reads characters, partial 
record mode 


KEADIBM 


READ IBM 


READ IBM 






S 


$IOLIB 


Ind. 


Reads two IBM 32-bit 
floating-point words from 
each Cray 64-bit word 


READP 


READP 


READP 






s 


$IOLIB 


Ind. 


Reads words , partial record 
mode 
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Table 2-1 • Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CPT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


REAL 


CQMPLX 


REAL 






SF 


$ARLIB 


Ind. 


Returns real part of a 
complex number 


RELEASE 


RLS 


RELEASE 






S 


$SYSLIB 


Dep. 


Releases a dataset 


REMARK 


REMARK 


REMARK 

REMARK2 

REMARKF 






s 

S 


$UTLIB 
$UTLIB 


Dep. 
Dep. 


Enters message in logfile 
Enters message and message 
ID in logfile 


REPRIEVE 


RPV 
ENDRPV 


SETRPV 
ENDRPV 




$SETRPV 
$ENDRPV 


s 

5 


$SYSLIB 
$SYSLIB 


Dep. 
Dep. 


Transfers control to a 
specified routine upon 
encountering a 
user-selected reprievable 
error condition 
Continues job step 
termination processing or 
clears an existing reprieve 
environment 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


f"» 1 1 TTrrvm 
v-»Cl-L x r L U1U 

CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


RERUN 


RERUN 


RERUN 






S 


$SYSLIB 


Dep. 


Allows user to set job 
rerunnability status 


REWD 


WCW 






$REWD 




$SYSLIB 


Dep. 


Rewinds dataset 


RPD 


RPD 






•pxsx J. 

$RFV $RFV% 

$RFA 

$RFF 

$RNOCHK 




$IOLIB 

$IOLIB 
$IOLIB 
$IOLIB 
$IOLIB 
$IOLIB 


Dep. 

Dep. 
Dep. 

Dep. 
Dep. 
Dep. 


Initializes for formatted 
read 

Cracks format; reads input. 
Vectorizes formatted read 
Terminates formatted read 
Read formatted, check; 
Read formatted, no check 


RLE 


RLB 






$RLB 




$SYSLIB 


Dep. 


Reads data directly from 
user area 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 




Library 


OS 
Dep 


Purpose 


CPT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Address 


Value 


RLD 


RLD 






$RLI 
$RLA 
$RLF 




$IOLIB 
$IOLIB 
$IOLIB 


Dep. 
Dep. 
Dep. 


Reads list-directed input 


RNB 


RNB 


RNB 




$RNB 


SF 


$SYSLIB 


Ind. 


Replaces trailing nulls 
with blanks 


ROT 




















CROT 


CROT 






S 


$SCILIB 


Ind. 


Applies complex Givens 


















plane rotation 




CROTG 


CROTG 






s 


$SCILIB 


Ind. 


Constructs complex Givens 


















plane rotation 




SROT 


SROT 






s 


$SCILIB 


Ind. 


Performs Givens plane 


















rotation 




SROTG 


SROTG 






s 


$SCILIB 


Ind, 


Constructs Givens plane 


















rotation 




SROTM 


SROTM 






s 


$SCILIB 


Ind. 


Performs modified Givens 


















plane rotation 




SROTMG 


SROTMG 






s 


$SCILIB 


Ind. 


Calculates a rotation 


















matrix as parameters for 


















modified Givens plane 


















rotation SROTM 
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Table 2-1* Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 

Deck 
Name 


Entry Type 


CPT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call Prom 
CAL Only 


Address 


Value 


RTOI 


RTOISS 
RTOIVS 
RTOIW 




RTOI% 

CivXvlf 




SF 
VP 
VF 
VF 


$ARLIB 
$ARLIB 
$ARLIB 
$ARLIB 


Ind. 
Ind. 
Ind. 
Ind. 


Raises real scalar to 
integer scalar power 
Raises real vector to 
integer scalar power 
Raises real scalar to 
integer vector power 
Raises real vector to 
integer vector power 


RTOR 
























RTORSS 




RTOR% 






SF 


$ARLIB 


Ind. 


Raises real scalar to 


real 




















scalar power 






RTORSV 




RTO%R% 






VP 


SARLIB 


Ind. 


Raises real scalar to 


real 




















vector power 






RTORVS 




%RTOR% 






VF 


9ARLIB 


Ind. 


Raises real vector to 


real 




















scalar power 






RTORW 




%RRO%R% 






VP 


$ARLIB 


Ind. 


Raises real vector to 


real 




















vector power 
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Table 2-1, Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call Prom 
CAL Only 


Address 


Value 


RU 


RU 






$RUI 

$RUV $RUV% 
$RUA 
%$RUV% 
$RUF 




$IOLIB 

$IOLIB 
$IOLIB 

$IOLIB 


Dep. 

Dep. 
Dep. 

Dep. 


Initializes for unformatted 
read 

Reads unformatted input 
Reads unformatted input 
into a vector 

Terminates unformatted read 


RUT 




















RUT 






RUTI% 




$IOLIB 


Dep. 


Initializes foreign dataset 


















read 










prppnft 

J\\J±Ul> 




$IOLIB 


Dep. 


Reads foreign dataset, full 


















record mode 










RUTDP% 




SIOLIB 


Dep. 


Reads foreign dataset. 


















partial record mode 










RUTF% 




$IOLIB 


Dep* 


Terminates foreign dataset 


















read 










FDGPOS* 




$IOLIB 


Dep. 


Gets foreign dataset 


















position 










FDSPOS* 




$IOLIB 


Dep. 


Sets foreign dataset 


















position 










FDBKSP% 




$IOLIB 


Dep. 


Backspaces foreign dataset 



SR-0014 



2-69 



I 



Table 2-1* Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 

Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


SAVE 


SVS 


SAVE 






S 


$SYSLIB 


Dep. 


Hakes a dataset permanent 


SCAL 


CSCAL 

CSSCAL 

SSCAL 


CSCAL 

CSSCAL 

SSCAL 






S 
S 
S 


$SCILIB 
$SCILIB 
$SCILIB 


Ind. 
Ind. 
Ind. 


Scales a complex array by a 
complex factor 
Scales a complex array by a 
real factor 

Scales a real array by a 
real factor 


SCATTER 


SCATTER 


SCATTER 






S 


$SCILIB 


Ind. 


Scatters a vector into 
another vector 


SCERP 


SCERP 


SCERP 




$SCERP 


s 


$SCILIB 


Ind. 


Processes $SCILIB errors; 
issues logfile error 
message $ then aborts with 
traceback . 



SR-0014 



2-70 



I 



Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


SCHED 


SCHED 






$SCHED% 




$UTLIB 


Dep. 


Schedules logical CPUs for 
user tasks 


SCNRM2 


SCNRM2 


SCNRM2 






SF 


$SCILIB 


Ind. 


Calculates the Euclidean 
norm (I2) of a complex 
array 


SDACCESS 


SDACC 


SDACCESS 






S 


$SYSLIB 


Dep. 


Allows a FORTRAN program to 
access system datasets 


SDSP 


SDSP 






$SDSP 




$SYSLIB 


Dep. 


Searches Dataset Parameter 
Tables for a dataset name 
and returns DSP address 


SEARCH 


OSRCHI 
OSRCHF 


OSRCHI 
OSRCHF 






S 

s 


$SCILIB 
$SCILIB 


Ind. 
Ind. 


Searches an ordered array 
for a target 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 

CAT, Onlv 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


SECOND 


SECOND 


SECOND 






S/SF 


$UTLIB 


Ind. 


Returns time since start of 
job in floating-point 
seconds 


SEGRES 


SEGRES 






$ SEGRES 
$SEGCALL 




$UTLIB 


Dep. 


Initializes execution of a 
segmented program and 
services intersegment 
subroutine calls 


SENSEBT 


BTMODE 


SENSEBT 






S 


$UTLIB 


Dep. 


Returns mode indicating 
bidirectional memory 
transfers are enabled or 
disabled 


SENSEFI 


PIMODE 


SENSEFI 






S 


$UTLIB 


Dep. 


Returns mode indicating 
floating-point interrupts 
permitted or prohibited 
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Table 2-1 • Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


SETBT 


BTMODE 


SETBT 






S 


$UTLIB 


Dep. 


Temporarily enables 
bidirectional memory 
transfers. 


SETBTS 


BTMODE 


SETBTS 






S 


$UTLIB 


Dep. 


Permanently enables 
bidirectional memory 
transfers 


SETFI 


PIMODE 


SETFI 






S 


$UTLIB 


Dep. 


Temporarily permits 
floating-point interrupts 


SETFIS 


PIMODE 


SETFIS 






S 


$UTLIB 


Ind. 


Enables floating-point 
interrupts until explicitly 
disabled 


SETPLIMQ 


PLOW 


SETPLIMQ 






S 


$UTLIB 


Ind. 


Processes CFT flowtrace 
option 
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Table 2-1 • Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


SETPOS 


SETPOS 
SPOS 
STPOS 
POS 

Q'PPOQ 
OirUD 

SETPOS 


SETPOS 

GETPOS 
SETPOS 




$ASPOS 

$FSPOS 

$GPOS 

$SPOS 

STPOS% 


S 

SF 
S 


$IOLIB 
$SYSLIB 
$SYSLIB 
$SYSLIB 

$SYSLIB 

$SYSLIB 

$SYSLIB 

$IOLIB 
$IOLIB 


Dep. 
Dep. 
Dep. 
Dep. 

Dep. 

Dep. 

Dep. 

L/ep. 
Dep. 

Dep. 


Set dataset position 

Set tape dataset position 

Asynchronously positions 

current dataset 

Finishes the asynchronous 

dataset positioning reguest 

Returns current dataset 

position 

Positions dataset to a word 
address 

ruoikiuiiD ua^c ua Lascu 

Returns current dataset 
position 

Positions dataset 


SFN 


RNB 


RNB 




$RNB 

SFN 


SF 


$SYSLIB 


Ind. 


Replaces trailing nulls 
with blanks 


SHIFT 


BOOLEAN 


SHIFT 






SF 


$ARLIB 


Ind. 


Shifts left circularly 



SR-0014 



2-74 



I 



Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


SHIFTL 


BOOLEAN 


SHIFTL 






SF 


$ARLIB 


ind. 


Shifts left; zero fill. 


SHIPTR 


BOOLEAN 


SHIFTR 






SF 


$ARLIB 


Ind. 


Shifts right; zero fill. 


SIGN 


REAL 


SIGN 






SF 


$ARLIB 


Ind. 


Transfers sign from one 
real number to another 


SIN 


COS 
COSV 


SIN 


SIN% 
%SIN% 


%SIN 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Computes sine 

Computes vectorized sine 


SINH 


COSH 
COSHV 


SINH 


SINH% 
%SINH% 


%SINH 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Computes hyperbolic sine 
Computes vectorized 
hyperbolic sine 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call Prom 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


SKIP 


SKIP 


SKIPR 
SKIPD 






S 
S 
S 


$I0LIB 
$IOLIB 
$IOLIB 


Dep. 
Dep. 
Dep. 


Bypasses a specified number 
of records in a dataset 
Bypasses a specified number 
of files in a dataset 
Positions a dataset at end 
of data 


SKIPBAD 


RCVRBAD 


SKIPBAD 






S 


$SYSLIB 


Dep. 


Skips to the first good 
data encountered 


SKIPU 


SKIPU 


SKIPU 






S 


$IOLIB 


Dep. 


Skips sectors on unblocked 
dataset 


SLERP 


SLERP 






SLERP% 




$SYSLIB 


Ind. 


Processes $SYSLIB errors; 
aborts with traceback. 
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Table 2-1 • Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


SLFT 


SDSP 






$SLFT 




$SYSLIB 


Dep. 


Searches Logical File Table 
for dataset name and 
returns LFT address 


SMACH 


SMACH 
CMACH 


SMACH 
CMACH 






SF 
SF 


$SCILIB 
$SCLIB 


Ind. 
Ind. 


Real function of an integer 
argument that returns Cray 
machine constants 
Computes complex Cray 
constants 


SNAP 


SNAP 


SNAP 






S 


$SYSLIB 


Dep. 


Prints current register 
contents on $OUT 


SNRM2 


SNRM2 


SNRM2 






SF 


$SCILIB 


Ind. 


Calculates Euclidean norm 
(1 2 ) of a real array 


SOLR 


SOLR 


SOLR 






S 


$SCILIB 


Ind. 


Solves second-order linear 
recurrences 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


SOLRN 


SOLRN 


SOLRN 






S 


$SCILIB 


Ind. 


Solves for only the last 
term of a second-order 
linear recurrence 


S0LR3 


S0LR3 


SOU? 3 






S 


$SCILIB 


Ind. 


Computes second-order 
linear recurrence of three 
terms 


SQRT 




















CSQRT 


CSQRT 


CSQRT% 




SF 


$ARLIB 


Ind, 


Computes complex square root 




CSQRTV 






%CSQRT 


VF 


$ARLIB 


Ind. 


Computes vectorized complex 


















square root 




DSQRT 


DSQRT 


DSQRT% 




SF 


$ARLIB 


Ind. 


Computes double-precision 


















square root 




DSQRTV 




%DSQRT% 


%DSQRT 


VF 


$ARL1B 


Ind. 


Computes vectorized 


















double-precision square root 




SQRT 


SQRT 


SQRT% 




SF 


$ARLIB 


Ind. 


Calculates square root 




SQRTV 




%SQRT% 


%SQRT 


VF 


$ARLIB 


Ind. 


Calculates vectorized 


















square root 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


SRC 


TM 






$SRC 




$SYSLIB 


Dep. 


Searches table for a 
specific value 


SSWITCH 


SSWITCH 


SSWITCH 






S/SF 


$UTLIB 


Dep. 


Tests pseudo sense switch 


STACK 


STACKAL 
STACKDE 






$STKOFEN 

$STKCR 
$STKUFEX 

3STKDE 
$STKUFCK 




$UTLIB 

$UTLIB 
$UTLIB 

$UTLIB 
$UTLIB 


Dep. 

Dep. 
Dep. 

Dep. 
Dep. 


Handles overflow of a stack 
during a subprogram entry 
Creates a stack 
Handles stack segment 

underflow in a subprogram 
exit 

Deletes a stack 

Checks for stack segment 

underflow in a subprogram 

exit 


STOP 


STOP 






$STOP 




$UTLIB 


Ind. 


Terminates current job step 
and advances job to next 
job step 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


CFT Standard 


Call From 
CAL Only 


CFT 

Call 
Type 


Library 


OS 
Dep 


Purpose 


Address 


Value 


STRMOV 


STRMOV 


STRMOV 






S 


$UTLIB 


Ind. 


Moves bytes 


SUBMIT 


SUBMIT 


SUBMIT 




$SUBMIT 


S 


$SYSLIB 


Dep. 


Places a job dataset into 
the COS input queue 


SUM 


CSUM 

SASUM 

SCASUM 

SSUM 


CSUM 

SASUM 

SCASUM 

SSUM 






SF 
SF 
SF 

SF 


$SCILID 
SSCILIB 
$SCILIB 

$SCILIB 


Ind. 
Ind. 
Ind. 

Ind. 


Sums the elements of a 
complex array 

Sums the absolute values of 
a real array 

Sums the absolute values of 

real and imaginary parts of 

a complex array 

Sums the elements of a real 

array 


SUSTSK 


SUSTSK 






$SUSTSK% 




$UTLIB 


Ind. 


Suspends execution of the 
calling task 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 
Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call Prom 
CAL Only 


Address 


Value 


SWAP 


SSWAP 


SSWAP 






b 
S 


$SCILIB 


inc • 
Ind. 


Exchanges specified 
elements of complex arrays 
Exchanges specified 
elements of two real arrays 


SYMDEBUG 


SYMDEBUG 


SYMDEBUG 
DEADBUG 






S 


$UTLIB 


Dep. 


Produces a symbolic dump 


SYNCH 


SYNCH 




SYNCH% 






$SYSLIB 


Dep. 


Synchronizes tape dataset 


TABLE 
MANAGER 


TM 
TM 
TM 
TM 


TMADW 
TMAMU 
TMATS 
TMINIT 






s 

SF 
S 


$UTLIB 
$UTLIB 
$UTLIB 


Dep. 
Dep. 
Dep. 


Reports TMGR statistics 
Allocates table space 
Initializes managed tables 



SR-0014 



2-81 



I 



Table 2-1, Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


TABLE 

MANAGER 

continued 


TM 
TM 
TM 
TM 
TM 
TM 


TMMEM 
TMMSC 
TMMVE 
TMPTS 
TMSRC 
TMVSC 






S 

SF 

S 

S 

SF 
SF 


SUTLIB 
$UTLIB 
$UTLIB 
$UTLIB 
$UTLIB 
SUTLIB 


Dep. 
Dep. 
Dep. 
Dep. 
Dep. 
Dep. 


Requests memory 
Searches table with mask 
Moves words 
Presets table space 
Searches table 
Searches vector table 


TABLES 


NCON 
PDD 

RANSED 






$IIN 

$IMX 

$IPX 

PDD 

RANFI 

RANFS 




$UTLIB 

$UTLIB 

SUTLIB 

SSYSLIB 

SARLIB 


Ind. 
Ind. 
Ind. 
Dep. 
Ind. 


Table of integer powers of 
ten 

Table of negative real 

powers of ten 

Table of positive real 

powers of ten 

Table of permanent dataset 

definitions 

Table for random number 
generator 


TADD 




















TPREC 


TADD 




TASS 




$ARLIB 


Ind. 


Performs triple-precision 










$TADD 








addition 










TASS% 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


TAN 


COT 
COTV 


TAN 


TAN% 
%TAN% 


%TAN 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind, 


Computes tangent 

Computes vectorized tangent 


TANH 


TANH 
TANHV 


TANH 


TANH% 
%TANH% 


%TANH 


SF 
VF 


$ARLIB 
$ARLIB 


Ind. 
Ind. 


Calculates hyperbolic 
tangent 

Calculates vectorized 
hyperbolic tangent 


TDIV 


TDSS 


TDIV 




TDSS 

TDSS% 

$TDIV 




$ARLIB 


Ind. 


Performs triple-precision 
division 


TIBCR 


TIBCR 






$TIBCR% 




$UTLIB 


Ind. 


Builds task information 
block 


TIBDE 


TIBDE 






$TIBDE% 




$UTLIB 


Ind. 


Deletes task information 
block 
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Table 2-1. Subprogram summary (continued) 







Entry Type 










Primary 


UPDATE 


CFT Standard 




CFT 








Reference 


Deck 




Call From 


Call 


Library 


OS 


Purpose 








Name 


Name 


Address 


Value 


CAL Only 


Type 




Dep 




TIME 




















DTTS 


DTTS 






S 


$SYSLIB 


Dep. 


Converts from date and time 


















to times tamp 




MTTS 


MTTS 






SF 


$SYSLIB 


Dep. 


Converts from a real-time 


















value to the corresponding 


















time stamp value 




TSDT 


TSDT 






S 


$SYSLIB 


Dep. 


Converts between times tamps 


















and the date and time as 


















ASCII strings 




TSMT 


1 OtVil 






SF 


$SYSLIB 


Dep. 


Converts from a timestarap 


















to the corresponding 


















real-time clock value 




UNITTS 


UNITTS 






SF 


$SYSLIB 


Dep. 


Returns the number of 


















time stamp units in a 


















specified number of 


















standard time units 


TMLT 




















TMLT 


TMLT 




TMSS 




$ARLIB 


Ind. 


Performs triple-precision 










TMSS% 








multiplication 










$TMLT 










TR 




















TR 


TR 






S 


$UTLIB 


Ind. 


Translates characters 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


TRBK 


TRBK 


TRBK 




$TRBK 


Q 


!6 SYS LIB 




Pr i nfc a 1 i cf o f- 

subroutines showing the 
path from the main program 
to the current subprogram 


TRBKLVL 


TKBKLV 
TRBKLV 


TRBKLVL 




TRBKLVL% 


s 


$UTLIB 
$SYSLIB 


Ind. 
Ind. 


Aids the traceback mechanism 
by returning information 
for the current level 


TREMAIN 


TREMAIN 


T REMAIN 






s 


$SYSLIB 


Dep, 


Returns time remaining for 
job execution in 
floating-point seconds 


TSKSTART 


TSKSTART 


TSKSTART 






s 


$UTLIB 


Ind. 


Initiates a task 


TSKTEST 


TSKTEST 


TSKTEST 






s 


$UTLIB 


Ind. 


Returns a value indicating 
whether the indicated task 
exists 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 

Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


TSKTUNE 


TSKTUNE 


TSKTUNE 






S 


$UTLIB 


Ind. 


Modifies scheduling 
parameters used by a 
multitasking subroutine 


TS RVALUE 


TS RVALUE 


TSKVALUE 






s 


JftUTLIB 

If/ \J J- U1U 


Ind- 


in the task control array 
used to create the 
executing task 


TSKWAIT 


TSKWAIT 


TSKWAIT 






S 


$UTLIB 


Ind. 


Waits for the indicated 
task to complete execution 


TSUB 


TSUB 


TSUB 




TSSS% 

TSSS 

$TSUB 




$ARLIB 


Ind. 


Performs triple-precision 
subtraction 


U32 


U32 


U32 






S 


$UTLIB 


Ind. 


Unpacks 32-bit words 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


U6064 


U6064 


U6064 






S 


$UTLIB 


Ind. 


Unpacks 60-bit words 


UEOF 


UEOPC 
UEOFK 
UEOFS 






$UEOFCL 

$UEOFKIL 

$UEOFSET 




$SYSLIB 
$SYSLIB 
$SYSLIB 


Dep. 
Dep. 
Dep. 


Sets the uncleared 
end-of-file flag in DSP 


UNIT 


UNIT 


UNIT 




UNITLB 


SF 


$IOLIB 


Dep. 


Waits for buffer I/O 
completion and returns 
status 


UNPACK 


UNPACK 


UNPACK 






S 


$SYSLIB 


Ind. 


Expands full words of data 
into a larger number of 
partial words 


USCCTC 


USCCTC 


USCCTC 






S 


$UTLIB 


Ind. 


Converts EBCDIC character 
to ASCII character 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 

Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


pa 1 T "From 

^>all A- L Will 

CAL Only 


Address 


Value 


USCCTI 


USCCTI 


USCCTI 






S 


$UTLIB 


Ind, 


Converts ASCII character to 
EBCDIC character 


USICTP 


USICTP 


USICTP 






S 


$UTLIB 


Ind. 


Converts integer to IBM 
packed decimal field 


USDCTC 


USDCTC 








S 


$UTLIB 


Ind. 


Converts IBM 
double-precision to Cray 
double-precision 


USDCTI 


USDCTI 


USDCTI 






S 


$UTLIB 


Ind. 


Converts Cray 
single-precision to IBM 
double-pr ec is ion 


USICTC 


USICTC 


USICTC 






S 


$UTLIB 


Ind. 


Converts IBM integer to 
Cray integer 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


USICTI 


USICTI 


USICTI 






S 


$UTLIB 


Ind. 


Converts Cray integer to 
IBM integer 


USLCTC 


USLCTC 


USLCTC 






S 


$UTLIB 


Ind. 


Converts IBM Logical to 
Cray Logical 


USLCTI 


USLCTI 


USLCTI 






S 


$UTLIB 


Ind. 


Converts Cray logical to 
IBM logical 


USPCTC 


USPCTC 


USPCTC 






S 


$UTLIB 


Ind. 


Converts IBM packed decimal 
field to integer 


USSCTC 


USSCTC 


USSCTC 






S 


$UTLIB 


Ind. 


Converts IBM 

single-precision to Cray 
single-precision 
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Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 


Address 


Value 


USSCTI 


USSCTI 


USSCTI 






S 


$UTLIB 


Ind. 


Converts Cray 
single-precision to IBM 
single-precision 


UTERP 


UTERP 






UTERP* 




$UTLIB 


Dep. 


Processes $UTLIB errors 


WAIO 


WAIO 


WOPEN 
PU1WA 

UL IrVrV 

WCLOSE 
SEEK 






S 
S 

S 
S 

s 


$I0LIB 
$IOLIB 

3IOLIB 

iJIOLIB 
SpIOLIB 


Dep. 
Dep. 

Dep. 

Dep. 
Dep. 


Opens a dataset on a disk 
and specifies dataset as 
word-addressable, random 
access 

Writes a number of words 
from memory to a 
word-addressable , random 
access dataset 
Reads a number of words 
from a word-addressable , 
random access dataset 
Closes a word-addressable, 
random access dataset 
Allows user no 
asynchronously read data 
into specified dataset 
buffers 



SR-0014 



2-90 



I 



Table 2-1. Subprogram summary (continued) 



Pr imary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


WB 


WB 


$WB 






S 


$IOLIB 


Dep. 


Initiates buffered output 


WC 


WCH 
WCH 






$WCHP 
$WCHR 




$SYSLIB 
$SYSLIB 


Dep. 
Dep. 


Writes characters in 
partial record mode 
Writes characters in record 
mode 


WE 


WWD 
WWD 






$WEOF 
$WEOD 




$SYSLIB 
$SYSLIB 


Deo. 
Dep. 


Writes EOF and/or EOR/ if 
necessary 

Writes EOD; writes EOF 
and/or EOR, if necessary. 


WFBUFFER 


WFBUFFER 






WFBUFFER 




$IOLIB 


Ind. 


Loads a character from 
$WFD's buffer 


WP 


WFD 






$WFI 

$WFV $WFV% 
%$WFV% 




$IOLIB 
$IOLIB 


Dep. 
Dep. 


initializes for formatted 
output 

Cracks format; writes 
output. 
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Table 2-1. Subprogram summary (continued) 



Pr iraary 
Reference 
Name 



UPDATE 

Deck 
Name 



Entry Type 



CFT Standard 



Address 



Value 



Call From 
CAL Only 



CFT 

Call 

Type 



Library 



OS 
Dep 



Purpose 



WF 

continued 



$WFA 

$WFF 

$WCHK 

$WNOCHK 



$IOLIB 

$IOLIB 
$IOLIB 
$IOLIB 



Dep. 

Dep. 
Dep. 
Dep. 



Cracks format; writes a 
vector to output. 
Finalizes write 
Write formatted, check; 
Write formatted, no check 



WHEN 



WHENEQ 

WHENNE 

WHENFLT 

WHENFLE 

WHENFGT 

WHENFGE 

WHENEQ 

WHENNE 

WHENILT 

WHENILE 

WHENIGT 

WHENIGE 



WHENEQ 

WHENNE 

WHENFLT 

WHENFLE 

WHENFGT 

WHENFGE 

WHENEQ 

WHENNE 

WHENILT 

WHENILE 

WHENIGT 

WHENIGE 



$SCILIB 



Ind. 



Returns all locations in an 
array that have a true 
relational value to the 
target. 



WLB 



WLB 



$WLB 



$SYSLIB 



Dep. 



Writes data directly into 
user area 
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Table 2-1 • Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 
Deck 
Name 


Entry Type 


CFT 

Call 

Type 


Library 


OS 
Dep 


Purpose 


CFT Standard 


Call From 
CAL Only 


Address 


Value 


WLD 


WLD 






$WLI 
$WLA 
$WLF 




$IOLIB 


Dep. 


Writes list-directed data 


WRITE 


WRITE 


WRITE 






S 


$IOLIB 


Ind. 


Writes words, full record 
mode 


WRITEC 


WRITEC 


WRITEC 






S 


$IOLIB 


Ind* 


Writes characters, full 
record mode 


WRITECP 


WRITECP 


WRITECP 






S 


$IOLIB 


Ind, 


Writes characters, partial 
record mode 



SR-0014 



2-93 



I 



Table 2-1. Subprogram summary (continued) 



Primary 
Reference 
Name 


UPDATE 

Deck 
Name 


Entry Type 


CFT 

Call 
Type 


Library 


OS 
Dep 


Purpose 


CPT Standard 


Call Prom 
CAL Onlv 


Address 


Value 




WRITIBM 


WRITIBM 






S 


$IOLIB 


Ind. 


Writes two IBM 32-bit 
floating-point words from 
each Cray 64-bit word 


wu 


WU 






$WUI 

$wuv $wuv% 
%$wuv% 

$WUA 
$WUF 




$IOLIB 

$IOLIB 
$IOLIB 

* TOT TXS 


Dep. 

Dep. 
Dep. 

Dep. 


Initializes for unformatted 
write 

Writes unformatted output 
Writes a vector to an 
output unit 
finalizes wrixe 


WOT 




















WUT 






WUTI% 




flSIOLIB 

iff Xv<U X kJ 


Deo. 


Initializes foreion dataset 


















write 










WUTD% 




4 TOT TT* 


i/ep • 


Ur <i ^ac f A^oinn a ^ a g 0 ^ 
i. Ceo LtKJLmyil uakClocLf 


















lull j,c?co£Ci muuc 










WUTDP% 






Dep. 


Writes foreign dataset r 


















partial record mode 










WUTF% 






Dep. 


Terminates foreign dataset 


















write 










FDWEOF* 




$IOLIB 


Dep. 


Writes foreign dataset, 


















end-of-f ile 
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Table 2-1 • Subprogram summary (continued) 



Primary 
Reference 
Name 



UPDATE 
Deck 
Name 



Entry Type 



CFT Standard 



Address 



Value 



Call Prom 
CAL Only 



CFT 

Call 

Type 



Library 



OS 
Dep 



Purpose 



WW 



WCW 



$WWDP 
$WWPU 



$WWDR 
$WWDS 



$SYSLIB 
$SYSLIB 



SSYSLIB 
$SYSLIB 



Dep, 
Dep, 



Dep, 
Dep. 



Writes words in partial mode 
Writes words in partial 
record mode with unused bit 
count 

Writes words in record mode 
Writes words in record mode 
with unused bit count 



XOR 



BOOLEAN 



XOR 



SP 



$ARLIB 



Ind. 



Forms logical difference 



ZTS 



TM 



$ZTS% 



$SYSLIB 



Dep. 



Clears table space 
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Table 2-2 . Pascal subprogram summary 









Call 








Primary 


Pascal Call 


from 








Ref. and 


Standard 


CAL 








UPDATE 






only 




Call 




Deck Name 


Address 


Value 


(X) 


Dep. 


Type 


Purpose 


P$$$HPAD 


P$$$HPAD 






Ind. 


SF 


Get address of heap 
control block 


P$ABORT 


P$ABORT 






Ind. 


S 


Abort job step 


P$CALLR 


P$CALLR 






Ind. 


SF 


Get name of calling 
routine 


P$CBV 


P$CBV 






Ind. 


S 


Call a call-by-value 
routine 


P$CONN£C 


P$CONNEC 






Ind. 


s 


Set file name 


P$DATE 


P$DATE 






Ind. 


s 


Get date 


P$DBP 


P&RREAK 


P$DBP 


X 


Ind. 


s 


Breakpoint checking 


P$DISP 


P$DISP 






Ind. 


s 


Dispose heap area 


P$DIVMOD 




P$DIVMOD 


X 


Ind. 


SF 


Integer division 


P$ENDP 


P$ENDP 






Ind. 


s 


End program 


P$EOF 


P$EOF 






Ind. 


SF 


End of file check 


P$EOLN 


P$EOLN 






Ind. 


SF 


End of line check 


P$GET 


P$GET 






Ind. 


S 


Read record 


P$HALT 


P$HALT 






Ind. 


S 


Terminate program 


P$JTIME 


P$JTIME 






Ind. 


SF 


Get job CPU time 


P$LOGMSG 


P$LOGMSG 






Ind. 


S 


Write $LOG message 


P$LSTREW 


P$LSTREW 






Ind. 


S 


Rewrite file without 
rewind 


P$MEMRY 


P$MEMRY 






Ind. 


SF 


Memory management 


P$MOD 




P$MOD 


X 


Ind. 


SF 


Integer modulus 


P$NEW 


P$NEW 






Ind. 


S 


Allocate heap area 


P$OSDBS 


P$OSDBS 






Dep. 


S 


Rewind dataset 


P$OSDDT 


P$OSDDT 






Dep. 


S 


Get date 


P$OSDEP 


P$OSDEP 






Dep. 


S 


Open dataset 


P$OSDJT 


P$OSDJT 






Dep. 


S 


Get job CPU time 


P$OSDLM 


P$OSDLM 






Dep. 


S 


Write $LOG message 


P$OSDPR 


P$OSDPR 






Dep. 


S 


Set prompt string 


P$OSDQI 


P$OSDQI 






Dep. 


s 


Query if dataset is 
interactive 


P$OSDRC 


P$OSDRC 






Dep. 


s 


Read characters 


P$OSDRP 


P$OSDRP 






Dep. 


s 


Enable reprieve 


P$OSDRW 


P$OSDRW 






Dep. 


s 


Read words 


P$OSDTM 


P$OSDTM 






Dep. 


s 


Get time of day 


P$OSDWC 


P$OSDWC 






Dep. 


s 


Write characters 


P$OSDWF 


P$OSDWF 






Dep. 


s 


Write EOF 


P$OSDWR 


P$OSDWR 






Dep. 


s 


Write record 


P$OSDXP 


P$OSDXP 






Dep. 


s 


Exit program 



I 
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Table 2-2, Pascal subprogram summary (continued) 









Call 








Primary 


Pascal Call 


from 








Ref. and 


Standard 


CAL 








UPDATE 






only 




Call 




Deck Name 


Address 


Value 


(X) 


Dep. 


Type 


Purpose 


P$PAGE 


P$PAGE 






Ind. 


S 


Start new page 


P$PUT 


P$PUT 






Ind. 


S 


Write record 


P$RB 


P$RB 






Ind, 


S 


Read Boolean 


P$RCH 


P$RCH 






Ind. 


s 


Read character 


P$READ 


P$READ 






Ind. 


s 


Read record 


P$READLN 


P$READLN 






Ind. 


s 


Read new line 


P$REPRV 


P$REPRV 






Ind. 


s 


Reprieve processing 


P$RESET 


P$RESET 






Ind. 


s 


Reset file 


P$REWRIT 


PJjREWRIT 






Ind. 


s 


Rewrite file 


P$RF 


P$RF 






Ind. 


s 


Read floating point 


P$RI 


P$RI 






Ind. 


s 


Read integer 


P$ROUND 




P$ROUND 


X 


Ind. 


SF 


ROUND function 


P$RSTR 


P$RSTR 






Ind. 


s 


Read string 


P$RTIME 


P$RTIME 






Ind. 


s 


Runtime timing 


P$RTMSG 


PSRTMSG 


P$DEBUG 




Ind. 


s 


Runtime messages 


P$RUNTIM 




P$RUNTIM 


X 


Ind. 


s 


Runtime 

initialization 
routine 


PtfSFRAME 


PtfSFRAME 






Ind. 


SF 


Returns pointer to 
caller 1 s stackf rame 


P$TIME 


P$TIME 






Ind. 


S 


Get time of day 


P$TIMER 


P$RTIME 


P$ TIMER 


X 


Ind. 


s 


Runtime timing 


P$TRACE 


P$TRACE 






Ind. 


s 


Stack walkback 


P$TRUNC 




P$TRUNC 


X 


Ind. 


SF 


TRUNC function 


P$WB 


P$WB 






Ind. 


S 


Write Boolean 


P$WCH 


P$WCH 






Ind. 


S 


Write character 


P$WEOF 


P$WEOF 






Ind. 


S 


Write end of file 


P$WI 


P$WI 






Ind. 


S 


Write integer 


P$WO 


P$WO 






Ind. 


S 


Write octal integer 


P$WR 


P$WR 






Ind. 


S 


Write real number 


P$WRITE 


P$WRITE 






Ind. 


s 


Write record 


P$WRITLN 


P$WRITLN 






Ind. 


s 


Write end of line 


P$WSTR 


P$WSTR 






Ind. 


s 


Write string 
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COMMON MATHEMATICAL 
SUBPROGRAMS 



3 



INTRODUCTION 

This section lists the following categories of mathematical subprograms. 
(Algorithms and performance statistics are listed in Appendixes A and B.) 

• Logarithmic 

• Exponential 

• Square root 

• Trigonometric 

• Hyperbolic 

• Boolean 



• Base value raised to a power 

• Double- and triple-precision arithmetic 

• Sixty-four bit integer division 

• Character 

• ASCII conversion 

• Miscellaneous math 

« Random number processing 

• Math tables 

The routines, whether presented in table form or in text form, list 
definition, argument and register information, and result type for each 
subprogram or subprogram group. In the routine definition, x and y 
indicate the first and second real arguments, respectively* Complex 
arguments are represented by z, which is x+iy. Argument and result types 
are represented by the following abbreviations. 
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R Real 

C Complex 

D Double precision 

CH Character 

I Integer 

B Boolean 

L Logical 

H Hollerith 

Each subprogram is listed in the tables with a code (CALL. SEQ. code) 
corresponding to one of the following calling sequences. 

NAME - Scalar, call-by-address (SA) 

Entry: 

arg± Address of first argument 
arg 2 Address of second argument (if present) 
Exit: 

(51) Result 

(52) Second word of result; present if complex or 
double -precis ion result. 



CAL usage: 



FORTRAN usage j 



CALL SQRT, {avg x ) 



The CFT compiler does not use scalar 
call-by-address for these subprograms. 



NAME% - Scalar , call-by-value (SV) 

(a) One word per argument <SVa) 
Entry: 

(51) First argument 

(52) Second argument (if present) 
Exit: 

(SI) Result 

(b) Two words per argument (SVb) 
Entry : 

(S1),(S2) First argument 

(53) , (S4) Second argument (if present) 
Exit: 

(SI) , (S2) Result 

(c) Three words per argument (SVc) 
Entry: 

(SI) , (S2) , (S3) First argument 

(54) , (S5) , (S6) Second argument 
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Exit: 

(S1),(S2), (S3) Result 



CAL usage: 



CALLV SQRT% 



FORTRAN usage! 



B=SQRT(A) 

The CFT compiler generates a scalar call-by-value 
call to SQRT% . 



%NAME - Vector, call-by-address (VA) 



Entry: 

arg x 

arg 2 
arg 3 

(VL) 
Exit: 
(VI) 
(V2) 



First word address of first argument 
Address of first increment 

First word address of second argument (if present) 
Address of second increment (if present) 
Vector length 

Result 

Second word of result? present if double^precision or 
complex result. 



NOTE 

For the vector call-by-address calling sequence, the 
arguments are taken from FWA, FWA+INCREMENT, 
FWA+2* INCREMENT, . • . , FWA+ ( (VL-1) * INCREMENT • 



CAL usage : 



CALL % SQRT , ( argi , arg r 2 ) 



FORTRAN usage; 



The CFT compiler does not use vector 
call-by-address for these functions. 



%NAME% - Vector call-by-value (W) 

(a) One word per argument (Wa) 
Entry : 

(VI) First argument 

(V2) Second argument (if present) 

(VL) Vector length 
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Exit: 

{VI) Result 



(b) Two words per argument (Wb) 
Entry: 

(VI) , (V2) First argument 
(V3) , (V4) Second argument (if present) 
Exit : 

(VI) , <V2) Result 



CAL usage: 



CALLV %SQRT% 



FORTRAN usage: 



DO 10 1=1,10 
10 B(I)=SQRT(A(I)) 



The CFT compiler generates a vector call-by-value 
call to %SQRT%. 



NOTE 



The range of many functions is given as |xl<oo„ This 
range is interpreted as x representable on the Cray 
computer as a floating-point number; that is, 
|xl<2 8192 or approximately |x|<10 2466 . 
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LOGARITHMIC ROUTINES 



Table 3-1 • Logarithmic routines 



General 


Entry 
Names 


Call 
Seq. 
Code 


Definition 


Arguments 


Func. 
Value 


Purpose 


No. 




Range 


Type 




AT Ap 

ALOG% 
%ALOG 
%ALOG% 


OA 

SVa 

VA 

Wa 


1 Oft f\t* 

10 y^ \x) or 
ln(x) 


1 


R 


0<x<» 




Common log • 


AiAJGlO 
ALOG10% 
% ALOGIO 
%ALOG10% 


SA 

SVa 

VA 

Wa 


logio (x) 


1 


R 


0<x<» 


R 


("Yvfiinl pv 1 on 


CLOG% 
%CLOG 
%CLOG% 


OA 

SVb 

VA 

Wb 


i arctan(y/x) 


1 


C 


0<x<» 


n 

w 


Double— "Dree « 
Natural log. 


DLOG 
DLOG% 
%DLOG 
%DLOG% 


SA 
SVb 
VA 
Wb 


ln(x) 


1 


0 


0<x<« 


D 


Double-prec. 
Common log. 


DLOGIO 
DLOGIO % 
%DLOG10 
%DLOG10% 


SA 
SVb 
VA 
Wb 




1 


D 


0<x<« 


D 
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EXPONENTIAL ROUTINES 



Table 3-2. Exponential routines 



General 
Purpose 


Entry 
Names 


Call 
Seq. 
Code 


Definition 


Arguments 


Func. 
Value 
Type 


No. 


Type 


Range 


Complex ex- 
ponentiation 


CEXP 
CEXP% 
%CEXP 
%CEXP% 


SA 
SVb 
VA 
Wb 


e x cos (y) + 
ie x sin(y) 


1 


C 


Ix|<2 13 ln2 
lyl<2 24 


C 


Double -prec. 
exponentia- 
tion 


DEXP 
DEXP% 
%DEXP 
%DEXP% 


SA 
SVb 
VA 
Wb 


e x 


1 


D 


|x|<2 13 ln2 


D 


Exponentia- 
tion 


EXP 
EXP% 
%EXP 
%EXP% 


SA 
SVa 
VA 
Wa 


e x 


1 


R 


|x|<2 13 ln2 


R 
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SQUARE ROOT ROUTINES 



Table 3*3. Square root routines 



General 
Purpose 


Entry 
Names 


Call 
Seq. 
Code 


Definition 


Arguments 


Func. 
Value 
Type 


No. 


Type 


Range 


Complex 
square root 


CSQRT 
CSQRT% 
%CSQRT 
%CSQRT% 


SA 
SVb 
VA 
Wb 


fV2(|z|+x) + 
i/l/2(lz|-x) 


1 


C 


0<x,y<» 


C 


Double-prec. 
square root 


DSQRT 
DSQRT% 
% DSQRT 
%DSQRT% 


SA 
SVb 
VA 
Wb 


^x or x^/^ 


1 


D 


0<_x<op 


D 


Square root 


SQRT 
SQRT% 
%SQRT 
%SQRT% 


SA 
SVa 
VA 
Wa 


j/x or x^/ 2 


1 


R 


0<x<oo 


R 
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TRIGONOMETRIC ROUTINES 



Table 3-4. Trigonometric routines 



General 


Entry 
Names 


Call 
Seq. 

Code 


Definition 


Arguments 


Punc. 
Value 
Type 


Purpose 


No. 


Type 


Range 


Arccosine 


ACOS 
AOOS% 
%ACOS 
%ACOS% 


SA 
SVa 
VA 
Wa 


arccos(x) 


1 


R 


|x|<L 


R 


Arcsine 


ASIN 
ASIN% 
%ASIN 
%ASIN% 


SA 
SVa 
VA 
Wa 


arcsin(x) 


1 


R 


Ix|<l 


R 


Arctangent 


ATAN 
ATAN% 
%ATAN 
%ATAN% 


SA 
SVa 
VA 
Wa 


arctan(x) 


1 


R 


|x|<« 


R 


Two-arg. 
arctangent 


ATAN2 
ATAN2% 
%ATAN2 
%ATAN2% 


SA 
SVa 
VAb 
Wa 


arctan (x/y) 


2 


R 


lx| , |y|<«> 
(x and y must 
not both be 
zero.) 


R 


Double-prec. 
arccosine 


DACOS 
DACOS % 
%DACOS 
%DACOS% 


SA 
SVb 
VA 
Wb 


arccos (x) 


1 


D 


|x|<L 


D 


Double-prec. 
arcsine 


DAS IN 
DASIN% 
%DASIN 
%DASIN% 


SA 
SVb 
VA 
Wb 


arcsine (x) 


1 


D 


Ixl<l 


D 
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Table 3-4. Trigonometric routines (continued) 



General 
Purpose 


Entry 
Names 


Call 
Seq, 
Code 


Definition 


Arguments 


Func* 
Value 
Type 


No. 


Type 


Range 


Double-prec. 
arctangent 


DATAN 
DATAN% 
%DATAN 
%DATAN% 


SA 
SVb 
VA 
Wb 


arctan(x) 


1 


D 


|x| < « 


D 


Double-prec. 
two-arg. 
arc tan. 


DATAN2 
DATAN2% 
%DATAN2 
%DATAN2% 


SA 
SVb 
VA 
Wb 


arctan(x/y) 


2 


D 


|x| , |y|<<» 
(x and y must 
not both be 
0.) 


D 


Cosine 


COS 
COS% 
%COS 
%COS% 


SA 
SVa 
VA 
Wa 


cos (x) 


1 


R 


|x|<2 2 4 


R 


Complex 
cosine 


CCOS 
CCOS% 
%CCOS 
%CCOS% 


SA 
SVb 
VA 
Wb 


cos (x)cosh (y)+ 
i sin(x)sinh(y) 


1 


C 


|x|<2 24 
Iy|<2 13 ln2 


C 


Double-prec ♦ 
cosine 


DCOS 
DCOS% 
%DCOS 
%DCOS 


SA 
SVb 
VA 
Wb 


cos (x) 


1 


D 


|x|<2 48 


D 


Sine 


SIN 
SIN 
%SIN 
%SIN% 


SA 
SVa 
VA 
Wa 


sin(x) 


1 


R 


|x|<224 


R 


Complex sine 


CSIN 
CSIN% 
%CSIN 
%CSIN% 


SA 
SVb 
VA 
Wb 


sin (x)cosh (y)+ 
i cos (x) sinh (y) 


1 


C 


|x|<2 24 
Iy|<2 13 ln2 


C 
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Table 3-4. Trigonometric routines (continued) 



General 
Purpose 


Entry 
Names 


Call 
Seq. 
Code 


Definition 


Arguments 


Func. 
Value 
Type 


No. 


Type 


Range 


Double-prec . 
sine 


DSIN 
DSIN% 
%DSIN 
%DSIN% 


SA 
SVb 
VA 
Wb 


sin (x) 


1 


D 


|x|<248 


D 


Cosine and 
sine^ 


COSS 
COSS% 
%COSS 
%COSS% 


SA 
SVb 
VA 
Wb 


y^cos (x) 
y2=sin(x) 


1 


R 


|x|<2 24 


R 


Tangent 


TAN 
TAN% 
%TAN 
%TAN% 


SA 
SVa 
VA 
Wa 


tan (x) 


1 


R 


|x|<2 24 


R 


Double-prec. 
tangent 


DTAN 
DTAN% 
%DTAN 
%DTAN% 


SA 
SVb 
VA 
Wb 


tan(x) 


1 


D 


|xK2 46 

|x-n|>0, 

1 n I =1 r 3 r 5f«*» 


D 


Cotangent 


COT 
COT% 
%COT 
%COT% 


SA 
SVa 
VA 
Wa 


cot (x) 


1 


R 


|x|<2 24 


R 


Double-prec . 
cotangent 


DCOT 
DCOT% 
%DCOT 
%DCOT% 


SA 
SVb 
VA 
Wb 


cot (x) 


1 


D 


|x|<2 46 
|x-n|>0, 
|n|=l,3,5, . . . 


D 



t Not FORTRAN callable 
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HYPERBOLIC ROUTINES 



Table 3*5. Hyperbolic routines 



General 
Purpose 


Entry 
Names 


Call 
Seq. 

Code 


Definition 


Arguments 


Func . 
Value 
Type 


No. 


Type 


Range 


Hyperbolic 
cosine 


COSH 
COSH% 
%COSH 
%COSH% 


SA 
SVa 
VA 
Wa 


(e x +e~ x )/2 


1 


R 


|x|<2 13 ln2 


R 


Hyperbolic 
sine 


SINH 
SINH% 
%SINH 
%SINH% 


SA 
SVa 
VA 
Wa 


(e x ~e~ x )/2 


1 


R 


Ix|<2 13 ln2 


R 


Hyperbolic 

cosine and 

. t 
sine 


COSSH 
COSSH% 
%COSSH 
%COSSH% 


SA 
SVb 
VA 
Wb 


y 1 ={e x +e" x }/2 
y 2 = ( e x -e- x )/2 


1 


R 


|xj<2 13 ln2 


R 


Hyperbolic 
tangent 


TANH 
TANH% 
%TANH 
%TANH% 


SA 
SVa 
VA 
Wa 


(e x -e~ x )/ 
(e x +e~ x ) 


1 


R 


|x|<2 13 ln2 


R 


Double-prec. 

hyperbolic 

cosine 


DCOSH 
DCOSH% 
%DCOSH 
%DCOSH% 


SA 
SVb 
VA 
Wb 


cosh(x) 


1 


D 


Ix|<2 13 ln2 


D 


Double-prec. 

hyperbolic 

sine 


DSINH 
DSINH% 
%DSINH 
%DSINH% 


SA 
SVb 
VA 
Wb 


sinh (x) 


1 


D 


Ix|<2 13 ln2 


D 



t Not FORTRAN callable 
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Table 3-5. Hyperbolic routines (continued) 



General 
Purpose 


Entry 
Names 


Call 
Seq. 
Code 


Definition 


Arguments 


Func. 

Value 
Type 


NO. 


Type 


Range 


Double-prec. 


DTANH 


SA 


tanh(x) 


1 


D 


Ixl<2l3i n2 


D 


hyperbolic 


DTANH 


SVb 












tangent 


% DTANH 


VA 














%DTANH% 


Wb 
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BOOLEAN ARITHMETIC ROUTINES 



These scalar subprograms in table 3-6 are external versions of CFT in-line 
functions. These functions can be passed as arguments to user-defined 
functions. They are all called by address and results are returned in 
register SI. 



Table 3-6. Boolean arithmetic routines 



Function 


Definition 


Arguments 


Function 
Value 


No. 


Type 


Type 


AND 


Computes logical product 0011 

0010 


2 


I,R,L,B 


B 


COMPL 


Computes logical complement 01 

10 


1 


I,R,L,B 


B 


EQV 


Computes logical 0011 
equivalence 1010 

0110 


2 


I,R,L,B 


B 


LEAD 2 


Counts the number of leading 
zero bits 


1 


I#R»L#B 


I 


MASK 


Returns a bit mask of ones. If 
0<arg<63, the mask is 
left-justif ied. If 64<arg<128, 
a right-justified mask of (128- 
argument) bits is returned. 


1 


I 


B 


NEQV 


Computes logical difference 
(same as XOR) 


2 


I,R,L,B 


B 


OR 


Computes logical sum 0011 

1010 

1011 J 


2 


I,R,L,B 


B 
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Table 3-6, Boolean arithmetic routines (continued) 



Function 


Definition 


Arguments 


Function 
Value 


No. 


Type 


Type 


POPCNT 


Counts the number of bits set 
to 1 


1 


I,R f L r B 


I 


POPPAR 


Returns 0 if even number of bits 
set; returns 1 if odd number of 
bits set 


1 


I ,R,L,B 


I 


SHIFT 


Performs circular shift of 
(arg^) to the left by (arg 2 ) 
bits 


2 


I,R,L,B 
I 


B 


SHIFTL 


Performs left shift of {arg^) 
by (arg2) bits with zero fill 


2 


I,R,L,B 


B 


SHIFTR 


Performs right shift of (arg\) 
by (a2»<?2) bi ts with zero fill 


2 


I,R,L,B 


B 


XOR 


Computes logical 0011 
difference 1010 

1001 


2 


I,R,L,B 


B 
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BASE VALUE RAISED TO A POWER ROUTINES 



FORTRAN routines implicitly call the following routines to raise a value 
to a power. When the call is from CAL, the VL register must be set for 
vector functions* The following routines are called by value. In table 
3-7 , a plus sign before the TYPE (as in +D) indicates the value must be 
positive. 



Table 3-7* Values raised to a power 









Arguments 




















Rpsult 


Definition 


Function 


Base 


Power 








Name 
















Type 


Reg 


Type 


Reg 


Type 


Reg 


Complex base raised 


CTOC% 


c 


Sl r S2 


C 


S3,S4 






to a complex power 


CTO%C% 


c 


S1,S2 


C 


V3,V4 


C 


VI rVZ 


(C**C) 


%CTOC% 


c 


Vl,V2 


C 


S3,S4 




Ttl XT') 




%CTO%C% 


c 


VI, V2 


C 


V3,V4 


C 


VI, V2 


Complex base raised 


CTOI% 


C 


S1,S2 


I 


S3 


C 


S1,S2 


to an integer power 


CTO%I% 


C 


S1,S2 


I 


V3 


c 


VI, V2 


(C**I) 


%CTOI% 


c 


VI, V2 


I 


S3 


c 


V1,V2 




%ero%i% 


c 


VI, V2 


I 


V3 


c 


VI, V2 


Complex base raised 


CT0R% 


c 


S1,S2 


R 


S3 


c 


S1,S2 


to a real power 


CT0%R% 


c 


S1,S2 


R 


V3 


c 


V1,V2 


(C**R) 


%CT0R% 


c 


VI, V2 


R 


S3 


c 


VI, V2 




%CT0%R% 


c 


VI, V2 


R 


V3 


c 


VI, V2 


Double-precision 


DT0D% 


+D 


S1,S2 


D 


S3,S4 


D 


S1,S2 


base raised to a 


DT0%D% 


+D 


S1,S2 


D 


V3,V4 


D 


VI, V2 


double-precision 


%DT0D% 


+D 


VI, V2 


D 


S3,S4 


D 


VI, V2 


power (D**D) 


%DT0%D% 


+D 


VI, V2 


D 


V3,V4 


D 


VI, V2 
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Table 3-7. Values raised to a power (continued) 









Arguments 




















Rash I t*. 


Definition 


Function 


Base 


Power 








Name 
















Type 


Reg 


Type 


Reg 




Reg 


Double -pr ec i s ion 


DTOI% 


D 


S1,S2 


I 


S3 


D 


S1,S2 


base raised to an 


DTO%I% 


D 


S1,S2 


I 


V3 


u 


X7~l I/O 


integer power 


%DTOI% 


D 


VI, V2 


I 


S3 


D 


VI, V2 


(D**I) 


%DTO%I% 


D 


V1 # V2 


I 


V3 


n 




Double-pr ec i s ion 


DTOR% 


+D 


S1,S2 


R 


S3 


D 


S1,S2 


base raised to a 


DTO%R% 


+D 


S1,S2 


R 


V3 


n 
u 


VX r VZ 


real power (D**R) 


%DTOR% 


+D 


VI, V2 


R 


S3 


D 


VI, V2 




%DTO%R% 


+D 


V1,V2 


R 


V3 




VX / V4 


Integer base raised 


ITOI% 


I 


SI 


I 


S2 


i 


SI 


to an integer power 


ITO%I% 


I 


SI 


1 


V2 


T 
X 


VX 


(1**1) 


%ITOI% 


I 


VI 


I 


S2 


I 


VI 




%ITO%I% 


I 


VI 


I 


V2 


T 


VJ_ 


Real base raised to 


RTOI% 


R 


bx 


T 

I 


SZ 


R 


SI 


an integer power 


RTO%I% 


R 


SI 


I 


V2 


R 


VI 






R 


VI 


I 


S2 


R 


VI 




%RTO%I% 


R 


VI 


I 


V2 


R 


VI 


Real base raised to 


RTOR% 


+R 


SI 


R 


S2 


R 


SI 


a real power 


RTO%R% 


+R 


SI 


R 


V2 


R 


VI 


(R**R) 


%RTOR% 


+R 


V2 


R 


S2 


R 


VI 




%RTO%R% 


+R 


V2 


R 


V2 


R 


VI 
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DOUBLE-PRECISION ARITHMETIC ROUTINES 



These routines are implicitly called by FORTRAN to do double-precision 
arithmetic. Double-precision arithmetic results are stored in two 64-bit 
computer words. In the first word, the high-order 16 bits contain the 
exponent and the low-order 48 bits contain the most significant part of 
the value. In the second word the low-order 48 bits contain the least 
significant part of the value. The first 16 bits of the second word must 
be 0. Double-precision arithmetic routines are called by value. Where 
two function names are given, use of the first one is preferred. 
Double-precision arithmetic routines are in table 3-8. 



Table 3-8. Double-precision arithmetic routines 









Arguments 




Result 


Definition 


Function 


Operand 1 


Operand 2 








Name 
















Type 


Reg 


Type 


Reg 


Type 


Reg 


Double -precis ion 


DASS% 


D 


S1,S2 


D 


S3,S4 


D 


S1,S2 


addition (D+D) 


DASV% 


D 


S1,S2 


D 


V3,V4 


D 


VI, V2 




DAVS% 


D 


VI, V2 


D 


S3,S4 


D 


VI, V2 




DAW% 


D 


VI, V2 


D 


V3,V4 


D 


VI, V2 


Double -prec i s ion 


DDSS% 


D 


S1,S2 


D 


S3,S4 


D 


S1,S2 


division (D/D) 


DDSV% 


D 


S1,S2 


D 


V3,V4 


D 


VI, V2 




DDVS% 


D 


V1,V2 


D 


S3,S4 


D 


VI, V2 




DDW% 


D 


VI, V2 


D 


V3,V4 


D 


VI, V2 


Dou ble -prec i s ion 


DMSS% 


D 


S1,S2 


D 


S3,S4 


D 


S1,S2 


multiplication 


DMSV% 


D 


S1,S2 


D 


V3,V4 


D 


VI, V2 


(D*D) 


DMVS% 


D 


VI, V2 


D 


S3,S4 


D 


VI, V2 




DMW% 


D 


VI, V2 


D 


V3,V4 


D 


VI, V2 


Double -prec i s ion 


DSSS% 


D 


S1,S2 


D 


S3,S4 


D 


S1,S2 


subtraction (D-D) 


DSSV% 


D 


S1,S2 


D 


V3,V4 


D 


VI, V2 




DSVS% 


D 


V3,V4 


D 


S3,S4 


D 


VI, V2 




DSW% 


D 


V3,V4 


D 


V3,V4 


D 


VI, V2 
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TRIPLE-PRECISION ARITHMETIC ROUTINES 



Triple-precision arithmetic results are stored in three contiguous 64-bit 
computer words. In the first word, the high-order 16 bits contain the 
exponent and the low-order 48 bits contain the first part of the value. 
The rest of the value is contained in the low-order 48 bits of the second 
and third words. The high-order 16 bits of the second and third words 
must be 0. If these routines are called from FORTRAN, the arguments must 
be passed in 3-word arrays. Triple-precision arithmetic routines are in 
table 3-9* 



Table 3-9. Triple-precision arithmetic routines 



Definition 


Name 


Call Type 


Entry Conditions 


Exit Conditions 


Triple-precision 


$TADD 


Value 


(Sl)=address of 


Result to address 


addition 






addend 

(52) =address of 

augend 

(53) =address of 

result 


in S3 




TADD*" 


Address 


arg^address of 
addend 

augend 
a2»g r 3= i address of 
result 


Result to address 
in avg^ 




TASS 


Address 


ar^^ address of 
addend 

augend 


(Si),(S2) f (S3) = 
result 




TASS% 


Value 


(S1),(S2),(S3) = 

addend 
(S4),(S5),<S6) = 

augend 


(S1),(S2),(S3) = 
result 



t FORTRAN entry point 
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Table 3-9, Triple-precision arithmetic routines (continued) 



Definition 


Name 


Call Type 


Entry Conditions 


Exit Conditions 


Triple-precision 


$TDIV 


Value 


(Sl)= t address of 


Result to address 


division 






dividend 

(52) =address of 

divisor 

(53) =address of 

result 


in S3 




TDIV f 


Address 


arg^=address of 
dividend 

divisor 
a2*03=address of 
result 


Result to address 
in avg^ 




TDSS 


Address 


arg ^address of 
dividend 

a2*02 =ad< 3 ress of 
divisor 


(SI), (S2),(S3)- 
result 




TDSS% 


Value 


(Sl),(S2) r (S3)- 
dividend 

(S4),(S5), (S6) = 
divisor 


(S1),<S2), (S3) = 
result 


Tr iple-pr ec ision 


$TMLT 


Value 


(Sl)=address of 


Result to address 


multiplication 






multiplier 

(52) ^address of 

multiplicand 

(53) =address of 

result 


in S3 




TMLT f 


Address 


arg 1 =address of 
multiplier 

ar 9 r 2~ ad(3ress °^ 

multiplicand 

argr^address of 
result 


Result to address 
in arg 3 




TOSS 


Address 


arg 1 =address of 
multiplier 

arg r 2 =:ad<3ress °^ 
multiplicand 


(S1),(S2),(S3) = 
result 




TMSS% 


Value 


(S1),(S2),(S3) = 
multiplier 

<S4), (S5),(S6) = 
multiplicand 


(S1),(S2),(S3)- 
result 



t FORTRAN entry point 
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Table 3-9 • Triple-precision arithmetic routines (continued) 



Definition 


Name 


Call Type 


Entry Conditions 


Exit Conditions 


Triple-precision 


$TSUB 


Value 


(Sl)=address of 


Result to address 


subtraction 






minuend 

(52) =address of 

subtrahend 

(53) =address of 

result 


in S3 




TSUB f 


Address 


minuend 
ap<79=address of 

subtrahend 
a7»g 3 =address of 

result 


Result to address 

in avg^ 




TSSS 


Address 


apg r * L =address of 
minuend 

aj^aaddress of 
subtrahend 


(SI) , {S2) , (S3) = 
result 




TSSS% 


Value 


<S1),(S2),(S3) = 
minuend 

(S4), (S5), (S6) = 
subtrahend 


(S1),(S2),(S3) = 
result 



t FORTRAN entry point 



Example of FORTRAN use: 

REAL A(3) ,B(3) ,RSLT(3) 
CALL TADD (A,B,RSLT) 



Example 1 of CAL use: 



Location 


Result 


■fiRWWJ. _ .„ r _ _ r _ . 




CALL 


TASS, (ARG1,ARG2) 



Example 2 of CAL use: 



51 1. 

52 0. 

53 0. 

54 1. 

55 0. 

56 0. 
CALLV TASS% 
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SIXTY-FOUR-BIT INTEGER DIVISION 



The 64-bit integer routines in table 3-10 are implicitly called by 
FORTRAN. They divide two 64-bit integers to produce a 64-bit integer 
result. The integer division routines are called by value. 



Table 3-10 . 64-bit integer division 



Definition 


Name 


Registers 


Result 
Type 


Entry 


Exit 


Quo. 


Rem. 


Scalar/scalar 


LDSS% 


S1,S2 


SI 


S2 


I 


Scalar/vector 


LDSV% 


S1,V2,VL 


VI 


V2 


I 


Vector/scalar 


LDVS% 


V1,S2,VL 


VI 


V2 


I 


Vector /vector 


LDW% 


V1,V2,VL 


VI 


V2 


I 
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CHARACTER FUNCTIONS 



The character functions in table 3-11 are called by address, A character 
address is 64 bits. These routines are implicitly called by FORTRAN for 
the character comparisons: GE # GT # LE, and LT. 



Table 3-11, Character comparison functions called from FORTRAN 



Definition 


Function 
Name 


Arguments 


Result 


Operand 1 


Operand 2 


Type 


Reg 


ASCII compare for GE 


LGE 


Character 


Character 


L 


SI 


ASCII compare for GT 


LGT 


Character 


Character 


L 


SI 


ASCII compare for LE 


LLE 


Character 


Character 


L 


SI 


ASCII compare for LT 


LLT 


Character 


Character 


L 


SI 


Find position of 
second argument as 
substring of first 
argument 


INDEX 


Character 


Character 


I 


SI 


Find length of 
argument 


LEN 


Character 




I 


SI 



Example : 

Call from CAL: 



CALL LGE, {ar*g 19 arg 2 ) 
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Address of character operand 1 
Address of character operand 2 

Logical result of comparison 

Call from FORTRAN: 

logical-LGE (eh^ , ehr 2 ) 

logical Logical result of comparison 

chri Character operand 1 

ohV2 Character operand 2 

The character functions in table 3-12 are called with the character 
address of the first operand in register SI and the address of the second 
operand in register S2. These routines are called only from CAL. 



Table 3-12- Character comparison functions called from CAL 



Definition 


Function 
Name 


Arguments 


Result 


Operand 1 


Operand 2 


Type 


Reg 


ASCII compare for GE 


$GE 


Character 


Character 


L 


SI 


ASCII compare for GT 


$GT 


Character 


Character 


L 


SI 


ASCII compare for LE 


$LE 


Character 


Character 


L 


SI 


ASCII compare for LT 


$LT 


Character 


Character 


L 


SI 


ASCII compare for EQ 


$EQ 


Character 


Character 


L 


SI 


ASCII compare for NE 


$NE 


Character 


Character 


L 


SI 



Entry: 

Exit : 
(SI) 
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Example : 



Call from CAL: 



CALLV $GE 



Entry: 



(SI) 
<S2) 



Address of first character operand 
Address of second character operand 



Exit: 
(SI) 



Logical result of comparison 



CHARACTER CONCATENATION AND STORE ROUTINES 

FORTRAN routines implicitly call the following routines to perform 
character concatenation. They are called in a manner similar to the I/O 
routines (see section 5 of this publication for a detailed description of 
I/O routines) , 

INITIALIZATION 

$CCI initializes concatenation for store. 
Call from CAL: 

CALLV $CCI 



Entry : 
(SI) 



Address of concatenated result 



TRANSFER 



$CCT transfers one character item to result. 
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Call from CAL: 



CALLV $CCT 

Entry: 

(SI) Address of item 

TERMINATION 

$CCF terminates transfer; blank-filled. 
Call from CAL: 

CALLV $CCF 



ASCII CONVERSION FUNCTIONS 

The functions in table 3-13 convert binary integers to or from 1-word 
ASCII strings (not CFT character variable) . The FORTRAN callable entry, 
xxx, uses the call-by-address sequence. 



NOTE 

These routines are not intrinsic to CFT. Their default 
type is real even though their results are generally 
used as integers. 
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Table 3-13. ASCII conversion 



Purpose 


Ent* 
Name 


Call 
Seq. 
Code 


Argument 1 


Argument 2 


Result 




Type 


Range 


Type 


Range 




Converts binary to 
decimal ASCII 
(right- just if ied, 
blank-filled) 


BTD 
BTD% 


SA 
SVa 


I 


0<xlD'99999999 






One word ASCII string 
(right- jus tif ied f 
blank-filled, decimal 
conversion) 


Converts binary 
to decimal ASCII 
(left- jus tif ied, 
zero-filled) 


BTDL 
BTDL* 


SA 
SVa 


I 


O^x^D 1 99999999 






One word ASCII string 
(left- justif ied, 
zero-filled, decimal 
conversion) 


Converts binary to 
decimal ASCII 
(right- justified, 
zero-filled) 


BTDR 
BTDR% 


SA 
SVa 


I 


O^x^D' 99999999 






One word ASCII string 
(right- just if ied, 
zero-filled, decimal 
conversion) 


Converts binary 
to octal ASCII 
( right- justif ied, 
blank-filled) 


BTO 
BTO% 


SA 
SVa 


I 


O^xlO ■ 77777777 






One word ASCII string 
(r ight- justif ied r 
blank-filled, octal 
conversion) 


Converts binary 
to octal ASCII 
(left-justified, 
zero-filled) 


BTOL 
RTOL% 


SA 
SVa 


I 


OlxlO 1 77777777 






One word ASCII string 
(left-justified , 
zero-filled, octal 
conversion) 


Converts binary 
to octal ASCII 
(right- jus tif ied, 
zero-f illed) 


BTOR 
BTOR% 


SA 
SVa 


I 


OlXlO f 77777777 






One word ASCII string 
(right- justif ied, 
zero-filled, octal 
conversion) 


Converts decimal 
ASCII to binary 


DTB 
DTB% 


SA 
SVa 


j 


( lef t- j ust if ied , 
zero-filled) 


I 


Opt . 

(error 
code) 


One word containing 
decimal equivalent 
of ASCII string. 
Error code: 0 if no 
error; -1 if error. 
Returned in second 
argument for CPT 
calls and in SO for 
CAL calls. If no 
error code argument 
is included for CPT 
calls, routine 
aborts on error . 


Converts octal 
ASCII to binary 


OTB 
0TB% 


5A 
SVa 


I 


Octal ASCII 
(left-justified, 
zero-filled) 


I 


Opt* 

(error 

code) 


One word containing 
octal equivalent 
of ASCII string* 

JZj L. L Ul l/UUc< U i. JL 

error; -1 if error. 
Returned in second 
argument for CFT 
calls and in SO for 
CAL calls. If no 
error code argument 
is included for CFT 
calls, routine aborts 
on error. 
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Example : 



Call from FORTRAN: 



result-BHD (arg) 



result Decimal ASCII result (right-justified, blank-filled) 



Call from CAL: 

CALLV BTD%,S1 

Entry : 

(SI) Integer value 

Exit: 

(SI) Decimal ASCII result (right-justified, blank-filled) 
Example : 

Call from FORTRAN: 

result=Dl!B (arg, err code) 
result integer value 

arg Decimal ASCII (left-justified, zero-filled) 

errcode 0 if conversion successful, -1 if error 

Call from CAL: 

CALLV DTB%,S1 



arg 



Integer argument 



Entry: 
(SI) 



Decimal ASCII (left- justified, zero-filled) 



Exit: 
(SI) 
(SO) 



Integer value 

Error code 0 if conversion successful 
-1 if error 



SR-0014 



3-27 



I 



PSEUDO VECTOR! ZATION ROUTINES 



Pseudo vectorization simulates vectorized math routines. See the PVEC 
macro in the Macros and Opdefs Reference Manual, CRI publication SR-0012. 



MISCELLANEOUS MATH ROUTINES 

The math routines can be divided into the following types, 

• Absolute value 

ABS 
CABS 
DABS 
IABS 

• Complex conjugate 

CONJG 

• Double-precision product of real arguments 

DPROD 

• Imaginary portion of complex number 

AIMAG 

• Modulo arithmetic 

AMOD 
DMOD 
MOD 

• Nearest integer 

NINT 
IDNINT 

• Nearest whole number 

AN INT 
DNINT 

• Positive difference 

DDIM 
DIM 

IDIM 

• Sign transfer 

DSIGN 
ISIGN 
SIGN 
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• Truncation 

AINT 
DINT 

• Type conversion 

CHAR 

CMPLX 

DBLE 

FLOAT 

INT 

ICHAR 

REAL 

Table 3-14 contains the miscellaneous math routines. 



Table 3-14, Miscellaneous math routines 



General 
Purpose 


Entry 
Name 


Call 
Seq. 
Code 


Argument Type 


Result 
Type 


Restrictions 


1 


2 


Real absolute 
value 


ABS 


SA 


R 




R 




Find the 
imaginary 
portion of 
a complex 
number 


AIMAG 


SA 


C 




R 


[x|, |yK<» 


Truncate 
to integral 
value 


AINT 


SA 


R 




R 


|x|<2 46 


Real modulo 

arithmetic 

y=xi-x 2 [xi/x 2 ] 


AMOD 


SA 
xi 


R 
*2 


R 

y 


R 


Ix 1 l<2 47 
0<|x 2 l<2*7 


Calculates 
nearest whole 
number 
Y=Lx+.5J 
if x^O 

y= L*-.5j 

if x<0 


ANINT 


SA 


R 




R 


|x| <2 46 



SR-0014 



3-29 



I 



Table 3-14, Miscellaneous math routines (continued) 



General 
Purpose 


Entry 
Name 


Call 
Seq. 
Code 


Argument Type 


Result 
Type 


Restrictions 


1 


2 




Complex 

absolute 

value 


CABS 
CABS% 
%CABS 
%CABS% 


SA 
SVb 
VA 
Wb 


C 




R 


|x|, |y |<°° 

x 2+y2< 00 

where complex 

argument 

z=x+iy 


Integer to 

character 

conversion 


CHAR 




I 




CH 




Convert two 
reals to a 
complex 


CMPLX 


SA 


R 


R 


C 




Complex 
conjugate 


CONJG 


SA 


C 




C 


IxJ, |y|<» 
where complex 
argument 
z=x+iy 


Determine 
double- 
precision 
absolute 
value 


DABS 


SA 


D 




D 


|x|<«> 


Convert 
real to 
double- 
precision 


DBLE 


SA 


R 




D 




Double- 
precision 
positive real 
difference 
MAX(0,x-y) 


DDIM 
DDIM% 
%DDIM 
%DDIM% 


SA 
SVb 
VA 
Wb 


D 


D 


D 


|x|, ly|<« 
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Table 3-14. Miscellaneous math routines (continued) 



General 


Entry 

Mama 


Call 
Code 


Argument Type 


Result 
Type 


AcSLl IClIOUS 


1 


2 


Positive real 

difference 

MAX(0,x-y) 


DIM 


SA 


R 


R 


R 


|x|, |y|<« 


Truncate 

precision 
numbers, 

y=[x] 
fraction 
last no 
rounding 


DINT 

%DINT 
%DINT% 


SA 
ovu 
VA 
Wb 


D 




D 


|x|<2 95 


Double - 

precision 

modulo 

arithmetic 

y=x 1 -x 2 [x 1 /x 2 ] 


DMOD 
DMOD% 
%DMOD 
%DMOD% 


SA 
SVb 
VA 
Wb 


D 
XI 


D 
x 2 


D 

y 


Ix^ 95 
0<|x 2 l<2 95 


Calculates 
nearest! 
integer ; 
defined as 

if x>0 

if x<0 


DNINT 
UNIN1% 
%DNINT 
%DNINT% 


SA 

faVD 

VA 

Wb 


D 




D 


|x|<2 95 


Double- 
precision 
product of 
two real 
arguments 


DPROD 


SA 


R 


R 


D 


Ixl , |y|<«> 
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Table 3*14. Miscellaneous math routines (continued) 



General 
Purpose 


Entry 
Name 


Call 
Seq. 

Code 


Argument Type 


Result 
Type 


Restrictions 


1 


2 


Transfers 
sign from 
one double- 
precision 
number to 
another 
defined as 
Y-lxJ if 

y= |xi | if 
x 2 <0 


DSIGN 


SA 


D 

(to 
which 
sign is 
trans- 
ferred) 


D 

(from 
which 
sign is 
trans- 
ferred) 


D 


|x x | f |x 2 K» 


Convert 
integer 
to real 


FLOAT 


SA 


I 




R 


|x|<2 46 


Integer 

absolute 

value 


IABS 


SA 


I 




I 


|x|< « 


Character 
to integer 
conversion 


I CHAR 




CH 




I 




Positive 
integer 
difference 
MAX(0,x-y) 


IDIM 


SA 


I 


I 


I 


Ixl ,|yl<« 
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Table 3-14, Miscellaneous math routines (continued) 



General 
Purpose 


Entry 
Name 


Call 
Seq. 
Code 


Argument Type 


Result 
Type 


Restrictions 


1 


2 




Nearest 
integer to a 
double- 
precision 
number; 
defined as 
Lx+.5J 
if x>0 
U-.5J 
if x<0 


IDNINT 
IDNINT% 
% IDNINT 
%IDNINT% 


SA 
SVb 
VA 
Wb 


D 




I 


lx| <2 46 


Truncate to 

integral 

value 


INT 


SA 


R 




I 


|x|<2 46 


Transfer 
sign from 
one integer 
to another 
defined as 
y=|x 1 | if 

x 2i° 

y 1 xjl | if 
x 2 <0 


I SIGN 


SA 


I 

(to 
which 
sign is 
trans- 
ferred) 


I 

(from 
which 
sign is 
trans- 
ferred) 


I 


IxjJ , |x 2 l <0 ° 


Perform 
64-bit modulo 
arithmetic 
on two 
integer 
scalars 

y=xi-X2[xi/x 2 ] 


MOD 

MOD% 

MODSS% 


SA 

SVb 

SVb 


I 

*1 


I 

x 2 


I 

y 

(Sl- 
reraain- 
der S2 
quot- 
ient) 


0<|x 2 l<2 63 
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Table 3-14 . Miscellaneous math routines (continued) 



General 
Purpose 


Entry 
Name 


Call 
Seq. 
Code 


Argument Type 


Result 
Type 


Restrictions 


1 


2 


Perform 

D1 U X 1I1ULJ U JLU 

arithmetic 
on two 
integer 
vectors 

<xi/x 2 ) 1 


%MOD% 

rl\JU v V 7> 


Wb 

V vu 


I 

x l 

ient) 


I 

x 2 


I 

y 

(VI- 
remain- 
der V2- 
quot- 


|x 1 |<2 63 


Perform 
64-bit 
modulo 
arithmetic 
on integer 
scalar and 
integer 
vector 


MODSV% 




I 

x l 

(divi- 
dend) 
(SI) 


I 

x 2*~ 
(divi- 
sor) 
(V2) 


I 
v 

(VI- 
remain- 
der V2- 
quot- 
ient) 


|x 1 l<263 


Perform 

O** D1C 

modulo 
arithmetic 
on integer 
vector and 
integer 
scalar 


MODVS% 




I 

(divi- 
dend) 
(VI) 


I 

(divi- 
sor) 
(S2) 


I 

lv±- 

remain- 
der S2- 
quot- 
ient) 


Ix 1 l<2 63 

n<* 1 v 1 <r*?63 
^ ' Xo 1 * 


nearest 
integer 
y=Lx+,5j 
if x>0 
y=|x-.5J 
if x<0 


NTWP 

Hill X 


ca 






T 

J- 


Ix I <2 4 *> 


Return real 
portion of 
a complex 
number 


REAL 


SA 


C 




R 
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Table 3-14. Miscellaneous math routines (continued) 



General 
Purpose 


Entry 
Name 


Call 
Seq. 
Code 


Argument Type 


Result 
Type 


Restrictions 


1 


2 


Transfer 


SIGN 


SA 


R 


R 


R 


UjJ , lx 2 l<co 


sign from 






(to 


(from 




one real 






which 


which 






number 






sign is 


sign is 






to another; 






trans- 


trans- 






defined as 






ferred) 


ferred) 






yHx^J if 














x^O 














y=|xjj if 














x 2 <0 















Examples: 
Call from CAL: 



CALL FLOAT, (arg) 



Entry: 

arg^ Address of integer argument 

Exit: 

(SI) Real result 



Call from FORTRAN: 



real-FlDhH (integer) 



real Real result 

integer Integer result 
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RANDOM NUMBER ROUTINES 



Table 3-15. Random number routines 



Purpose 


Entry 
Name 


Call 
Seq. 
Code 


Argument Type 


Result 

Type 


Generates 

random 

numbers 


RANF 

RANF% 

%RANP 

4 RAMP St 


SA 

SVa 

VA 

V vCL 


No arguments 
required (VL) 

assumed correct 
versions 


R 


Returns 

current 

seed of 

random 

number 

generator 


RANGET 
RANGET% 


SA 
SVa 


I (optional) 


I 


Sets 

random 

seed 


RANSET 
RANSET% 


SA 
SVa 


I (optional) 


I 



NOTE 

When the seed of the random number generator is reset, 
RANSET does not store the supplied argument as the 
first value in the buffer of the random number seeds. 
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Examples : 



RANF 



Call front CAL: 



CALL RANF 
CALLV RANF% 
CALL %RANF 
CALLV %RANF% 



Call from FORTRAN: 



randonpRM&F ( ) 



(Scalar version) 



DO 10 I=l r 10 
10 RANDOM (I)=RANF( ) (Vector version) 



RANGE T 

Call from CAL: 

CALL RANGE T 
CALLV RANGET% 



Call from FORTRAN: 



CALL RANGET {iseed) 
isee<i=RANGET( ) 



iaeed Contains the current seed 
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RANSET 



Call from CAL: 



CALL RANSET 
CALLV RANSET% 



Call from FORTRAN: 



CALL RANSET (ivatue) 
dummy =BJ±RSE?r ( ivalu e) 



MATH TABLES 

The tables in the following list contain no executable instructions 
but are referenced by other library routines. 

$IIN Contains integer powers of 10 in the range of 10° to 
1018 

$IMX Contains double-precision floating-point representation of 
negative powers of 10 in the range of 10° to io~ 4096 

$IPX Contains double-precision floating-point representation of 
positive powers of 10 in the range of 10° to 10 4096 

RANPI Contains the current index to the seed buffer for the 
random number generator 

RANPS Contains 128 random number seeds in a buffer 
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SCIENTIFIC APPLICATIONS 4 
SUBPROGRAMS 



INTRODUCTION 

The scientific applications subprograms are written to run optimally on 
the Cray computer. These subprograms use the call-by-address convention 
when called by a FORTRAN or CAL program. See the introduction to this 
manual for details of the call-by-address convention. 

The subprograms are grouped as follows: 

• Basic linear algebra subprograms 

• Other linear algebra subprograms 

• Functions and linear recurrence routines 

• Linpack routines 

• Eispack routines 

• Matrix inverse and multiplication routines 

• Fast Fourier transform routines 

• Filter routines 

» Gather, scatter routines 

• Search routines 

• Sort routine 

BASIC LINEAR ALGEBRA SUBPROGRAMS 

The Cray computer user has access to a subset of the Basic Linear Algebra 
Subprograms (BLAS) , a package of 22 CAL-coded routines. Only the 
single-precision and complex versions of the BLAS are included in the 
package. The following operations are available. 
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• Dot products 

• Vector scaling 

• Vector copy and swap 

• Givens transformations 

• Pivot search (maximum element) 

• Euclidean norm 

• A constant times a vector plus another vector 

• Sum of absolute values 

Each BIAS routine has a real version and a complex version. Type and 
dimension declarations for variables occurring in the subprograms must 
appear in the following manner, 

REAL SX(mx) , SY(my), SA 

REAL C, S, A, B, PARM(4) , Dl, D2, Bl, B2 

COMPLEX CX(mx) , CY (my), CA 

where dimensions marmax (1,N* I INCXl ) , my=max (l r N* I INCYI ) , and N is the 
array length of the input vectors. In all routines, if N<0, inputs and 
outputs return unchanged. 

Type declarations for function names follow: 
INTEGER ISAMAX, ICAMAX 

REAL SASUM, SCASUM, SDOT, SNRM2 f SCNRM2 

COMPLEX CDOTC, CDOTU 

The declaration for complex functions is especially important to avoid 
type conversion to zero imaginary parts. 

Arrays can have non-unit spacing between elements. The parameters inex 
and iney specify skip distances, allowing vector operands to be 
noncontiguous elements of memory, A value of 1 indicates contiguous 
elements. When a negative skip distance is specified, the operands are 
used in reverse order. Since FORTRAN dimension statements allow only 
positive integers for array lengths, references must be confined to array 
elements having only positive indexes. Therefore, if spacing between 
elements is negative, reversing the orientation of number is required. 
Thus if array SX contains elements xl, x2,,,,, xn, the contents of memory 
spaces SX{1), SX(2),.,., SX(rc) are 

xl,x2,,,,,xn if incoc=l, or xn,xn-l, • . . ,xl if inex*-!* 
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That is, element xi is in location SX(l+(i-l) *incx) if inex>0 or 
in location SX(1+ [n-i) *ineo£) if inex<Q* Location SX(1) is passed 
regardless of the sign of inex. 



Example : 

Let X(l)=1.0, X(2)=2.0, X<3)~3.0,..., X{10)=10. The real function, 
SASUM, which sums the absolute value of elements of a vector, is 
evaluated as follows. 



SASUM(5,X,2)=(( ((1,0+3.0) +5,0) +7,0) +9.0) , and 
SASUM(5,X, -2) =((((9.0+7.0) +5.0) +3.0) +1.0) 

Table 4-1 contains the purpose, name, and type of each BLAS. 



Table 4-1. Basic linear algebra subprograms (BLAS) 



Purpose 


Name (parameter list) 


Type 


Index of element with 
maximum absolute value 


ISAMAX (n , sx,inex) 
ICAMAX (n r ox, inex) 


Integer function 


Sum of the absolute 
values 


SASUM ( n , &x, inex) 
SCASUM(n, ax, inex) 


Real function 


Constant times a vector 
plus another vector 


saxpy (n, sa,sx, inex, ey, iney) 
CAXPY(w, ea, ex, inex, ey, iney) 


Routine 


Copy one array into 
another 


SCOPY (n,sx,in ex, sy , iney) 
CCOPY ( n, ex, inex, ey, iney) 


Routine 


Euclidean norm of 
array 


SNRM2 ( n, sx, inex) 
SCNRM2 ( n , ex, inea*) 


Real function 
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Table 4-1. Basic linear algebra subprograms (BIAS) (continued) 



Purpose 


Name {parameter list) 


Type 


Dot product 


SDOT (n , sx, inox, sy , iney) 

CDOTC (n, ox, incx, oy, inoy) 
CDOTU (n , ox, inex, ey, inoy) 


Real function 
Complex function 


Construct Givens plane 
rotation 


SRQTG{a,b,e,s) 


Routine 


Apply Givens plane 
rotation 


SRQT{n, sx, inex, sy, inoy ,e,s) 


Routine 


Construct Givens 
modified plane rotation 


SROTMG {d\ 9 d2,bl,b2,param) 


Routine 


Apply Givens modified 
plane rotation 


SROTM (n,sx,inox,sy ,in oy , 
param) 


Routine 


Scale array 


SSCAL {n,sa,sx, inex) 
CSSCAL (n 9 sa,ox, inex) 
CSCAL (n , oa, ox, inex) 


Routine 




Swap two arrays 




SSWAP (n , sx, inox, sy ,inoy) 
CSWAP (n , ox, inox, ey,inoy) 


Routine 



INDEX OF ELEMENT HAVING MAXIMUM ABSOLUTE VALUE 

These integer functions find the first index of the largest absolute 
value of the elements of a vector. 



ISAMAX returns the first index i such that 

I x ^ | =max |x j | : j=l, . . . r n . 
where x^ is an element of a real vector. 
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Call from FORTRAN : 



imax=lSAMAX (n , sx, inox) 

n Number of elements to process in the vector to be searched 

(n=vector length if inex=l; ^vector length/2 if 
incoc=2; etc.) 

8x Real vector to be searched 

inex Skip distance between elements of sx. For contiguous 

elements , inco^l. 

ICAMAX determines the first index i such that 

I Real (x.^) l + llmagtxi) |=max| I Real (Xj) | + |Imag(Xj) I :j=l,...,nj . 
where Xj is an element of a complex vector. 
Call from FORTRAN: 

irnax^ ICAMAX (n, ox, inex) 

n Number of elements to process in the vector to be searched 

(tt=vector length if inex^l- rF=vector length/2 if 
inox^2; etc.) 

ox Complex vector to be searched 

inox Skip distance between elements of ax. For contiguous 

elements, inox?=l. 

SUM OF THE ABSOLUTE VALUES 

These real functions sum the absolute values of a vector. 



SASUM computes 
n 

i=l 

where x^ is an element of a real vector. 



SR-0014 



4-5 



I 



Call from FORTRAN: 



sutfF=SASUM (n , sx,inex) 

n Number of elements in the vector to be summed 

sx Real vector to be summed 

inox Skip distance between elements of ax. For contiguous 

elements, incx=l. 

SCASUM computes 
n 

sum- 2 jlRealfxi) |+| Imagtx^) | } 
i=l 

where x^ is an element of a complex vector. 
Call from FORTRAN: 

su77?=SCASUM (n,cx r inox) 

n Number of elements in the vector to be summed 

ex Complex vector to be summed 

inox Skip distance between elements of ex. For contiguous 

elements , incofcl . 

CONSTANT TIMES A VECTOR PLUS ANOTHER VECTOR 

These subroutines add a scalar multiple of one vector to another. 

SAXPY computes 
Y=aX+Y 

where a is a real scalar multiplier and X and Y are real vectors. 
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Call from FORTRAN; 



call saxpy (n,sa,sx,inex, 8y t iney) 



n Number of elements in the vectors 

sa Real scalar multiplier 

sx Real scaled vector 

inex Skip distance between elements of ex* For contiguous 

elements, inex*=l. 

sy Real result vector 

iney Skip distance between elements of sy. For contiguous 

elements , iney*l • 



CAXPY computes 
Y=aX+Y 

where a is a complex scalar multiplier and X and Y are complex vectors. 
Call from FORTRAN: 

CALL CAXPY(n,ea,ex,incx t ey,iney) 



n Number of elements in the vectors 

ea Complex scalar multiplier 

ax Complex scaled vector 

inex Skip distance between elements of ex. For contiguous 

elements, incx=l. 

ey Complex result vector 

iney Skip distance between elements of ey. For contiguous 

elements, iney=l. 
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COPY ONE ARRAY INTO ANOTHER 
These subroutines copy a vector, 

SCOPY copies a real vector 

Yi=x^ : i**l, . . . ,n 
where x± and y A are elements of real vectors. 
Call from FORTRAN: 

call SCOPY (n f sx,inox,sy,inoy) 



n Number of elements in the vector to be copied 

sx Real vector to be copied 

inox Skip distance between elements of sx. For contiguous 

elements, iwl. 

sy Real result vector 

inoy Skip distance between elements of sy* For contiguous 

elements, incy=l* 



CCOPY copies a complex vector 

Yi^x^: i=l, . • * , n 
where x A and y^ are elements of complex vectors. 
Call from FORTRAN; 

CALL CCOPY (n,ox, inox, oy, inoy) 



n Number of elements in the vector to be copied 

ox Complex vector to be copied 

inex Skip distance between elements of ox* For contiguous 

elements, inox^l. 

oy Complex result vector 

inoy Skip distance between elements of oy. For contiguous 

elements, incy~l* 
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COMPUTE AN INNER PRODUCT OF TWO VECTORS 

These real and complex functions compute an inner product of two vectors, 

SDOT computes 
n 

dot= 2 x i y i 
i=l 

where and y^ are elements of real vectors. 
Call from FORTRAN: 

dot-SDOT (n,sx, inox, sy, inoy) 

n Number of elements in the vectors 

sx Real vector operand 

inox Skip distance between elements of sx 9 For contiguous 

elements, ineo$=l + 

sy Real vector operand 

inoy Skip distance between elements of sy. For contiguous 

elements, inoy-1. 

CDOTC computes 
n 

edot= 2 x^ 
i=l 

where x^ and y^ are elements of complex vectors and x^ is the 
complex conjugate of x^. 

Call from FORTRAN: 

<3£?c£=CD0TC (n , ex, inox, oy , inoy) 
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n Number of elements in vector 

ex Complex vector operand 

incx Skip distance between elements of ex. For contiguous 

elements r incx*! . 

cy Complex vector operand 

iney Skip distance between elements of cy* For contiguous 

elements , incy=l . 



CDOTU computes 
n 

cdot=* 5 x i y i 
i«l 

where x^ and are elements of complex vectors. 
Call from FORTRAN: 

ccfot^CDOTU (n, ex, inox, cy, iney) 



n Number of elements in vector 

ox Complex vector operand 

inex Skip distance between elements of ex* For contiguous 

elements, inc&*l+ 

ay Complex vector operand 

iney Skip distance between elements of cy. For contiguous 

elements , iney-l . 



EUCLIDEAN NORM OF AN ARRAY (1 2 NORM) 

These real functions compute the Euclidean or 1 2 norm of a vector* 

SNRM2 computes 
/n 

euenorwp* I 2 | x | 
where x^ is an element of a real vector. 
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Call from FORTRAN: 



euonovvR* SNRM2 (n,8X,inex) 

n Number of elements in vector 

sx Real vector operand 

incx Skip distance between elements of ax. For contiguous 

elements, inez^l. 

SCNRM2 computes 
/n 

eucnorrri= I ? XXt 
\ i=l 1 i 

where x^ is a complex vector and x^ is the complex conjugate of xj. 
Call from FORTRAN : 

eucnovm=SCNBM2 {n , ox r incx) 

n Number of elements in vector 

ex Complex vector operand 

incx Skip distance between elements of ex. For contiguous 

elements f incx*l. 

CONSTRUCT GIVENS PLANE ROTATION 

SROTG computes the elements of a Givens rotation matrix. The following 

call calculates the parameters r r z f c, s, from input coordinates a,b as 
in equation 1. 

Call from FORTRAN: 

CALL SROTG(a,b,C r s) 
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a 

b 

G 
3 



Scalar a of equation 1 
Scalar b of equation 1 
Scalar cosine of equation 1 
Scalar sine of equation 1 



Equation 1; 



c 
-s 





"a" 




b 

- 



z must contain enough information to reconstruct c,s; that is, from plane 
coordinates a/b f SROTG calculates 



r=sgn(a) * /a 2 +b 2 if |a|>|b| 
=sgn(b) * ^a2+b2 if |a|<_|b| 



and 



c=a/r if r/0 

=1 if r=0 

s=b/r if r^O 

=0 if r=0. 



Parameter z is 



z=s if !a|>|b| or a=b=0 
=l/c if 0<|aMb| 
-1 if |b|>|a|=0 



Note that if |z|<l, then 
s=z 

c=/l-z 2 
while if |z|>l, then 
c=l/z 



s=l4-(l/z) 2 . 

The subroutine uses parameters a and b and returns r f z,c,s, where r 
overwrites a and z overwrites b. 
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APPLY GIVENS PLANE ROTATION 



This subroutine performs a matrix multiplication. If the coefficients 
e and s satisfy e*c+&*s=l.Q, the transformation is a Givens rotation. 
The coefficients e and s can be calculated from sx and sy using SROTG. 

SROT computes equation 2 on each pair of elements xj, y^ of real 
arrays. 

Call from FORTRAN: 

CALL SROT {n,sx,inex,sy,incy r c, s) 



n Number of elements in vector 

sx Real vector to be modified 

inex Skip distance between elements of sx. For contiguous 

elements, incz^l. 

sy Real vector to be modified 

incy Skip distance between elements of sy+ For contiguous 

elements, incy^l* 

e Real cosine of equation 2. Normally calculated using SROTG. 

s Real sine of equation 2* Normally calculated using SROTG. 



Equation 2: 




SROT returns without modification to any input parameters if c~l and 
CONSTRUCT MODIFIED GIVENS PLANE ROTATION 

SROTMG computes the elements of a modified Givens plane rotation matrix. 
CALL SROTMG (d± , d 2 1 , & 2 * V avam } 
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SROTMG sets up parameters pavam from inputs d\ 9 d 2 $ hi, b 2 . The following 
is a brief description* 



An application of the Givens plane rotation 



x 9 



X 



y 



X 



y 



can be written in a form such that repeated applications require matrix 
multiplications by matrices containing only two non-unit elements. Row 
transformations require only 2N multiplications, rather than 4N. Scale 
factors di,d 2 are defined such that 



X 




Vd{ 0 




h 


D V2 


h 


y 

- _ 




0 VSJ 








b 2 



where the scaling upon each application of the G's is updated. Let H be a 
matrix 



H = 



h ll h 12 



h 21 h 22 
such that 

G 



x 



y 

L -I 



D'V2 H 



where D' 1 / 2 * diag 



J& , Jd 



contains the updated scale factors; 



i 2 ; 

therefore, H is chosen according to equation 3 or 4. 
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Equation 4: 





h 21 /*2 h 22/ " y-j/^T* d 2 ° 

Coefficients c and s are determined by equations 5 and 6. 

Equation 5: 

c = x m d ih 



Equation 6: 



s - y_ m d 2 b 2 

Equation 4 shows that the d's are going to be scaled by c or s if two 
of the ^'s are to be unity. Two cases, |c|>|s| and IsMcl, are 
considered so that the d's are scaled down the least upon repeated 
applications. 



Case 1: 

If |c|>|s| (which from equations 5 and 6 is the same as Idj^l Hdj&jl ) ' 
the solutions for equation 4 are determined by equation 7. 



Equation 7: 

fcll =7l 22 =1 

Case 2: 

If |s|>Jc| (which is \d 2 b^\>\d b \) , equation 8 is chosen. 
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Equation 8; 

h 12 =-h 2 i =* 1. 



Distinguishing the two cases, |cl>_l or |s|> 1 is the updating 
factor. Then the complete solutions for D IJ -/* and H are as follows. 



Case 1: 

In case l r where Id > |s| or \^^>\ \ > ^^2 the follow;i - n 9 solutions for 
H are chosen: 

h =1 h = ^2 
11 12 cfi&i 

*2l" "SI h 22 =1 



and scale factors £?2 are updated to 

1 2 

c?l « d\/ u - o d\ 

($2 = <$2 /u = e d 2 



where 

u = ctei (H) » 1 + a 2 2 

ii ti fT t 

and since x = r, y = 0, and 2^= x /y/d^hen b^ i .w is updated. 

Case 2: 

In case 2, where |s|_>|c| or \d b^\<_\d 0 bh , the following solutions for H are 
chosen • 11 * z 

>* 21 = -l h = 1 /£ 2 
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and scale factors are updated to 

d \ = d 2/ u 
d 2 " d l/ u 

with 

u * det(H) = 1 + dlbl 

d 2 b 2 

and the a: 1 factor becomes 
i 

Case 3: 

Let m = 4096, Whenever the parameters are updated to be outside 
the window 

<m)~ 2 < |<2,| < (m) 2 
— t — 

which preserves about 36 = 48 - 12 bits or 10 decimal digits of 
precision, all parameters are rescaled such that the d^'s are within 
that window. However, if either of the d^s is 0, no rescaling 
action is taken. 



Underflow: 

If \dj\<{m) f then the following is set. 

t i 2 * 1 -1 

d t=d..{m) , 7i . := fc. . (m) , 

% % tl tl 

■ » * 1 -1 

11 12 t2 



Overflow: 



1 2 
If I-Mw) , then we set 

d\ t =d'..(mr 2 , h ix ^.W, 

11 II 

SROTMG modifies the input parameters Dl r D2 f and Bl and returns the array 
PARAM according to the following schedule: 
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Case 4: 

If ABS (D1*B1*B1) .GT.ABS (D2*B2*B2) , then 

PARAM (1)=0 

PARAM(3) =-B2/Bl 

PARAM ( 4 ) =D2 *B2/D1 *B 1 
and parameters Dl, D2, and Bl are written over by 

D1=D1/U 

D2=D2/U 

B1=B1*U 
where 

U=1.+(D2*B2*B2)/(D1*B1*B1) . 
Case 5: 

If ABS(D2*B2*B2) .GE.ABS (Dl*Bl*Bl) , then 
PARAM (1) =1 . 
PARAM (2) =D1*B1/D2*B2 
PARAM(5)=B1/B2 

and parameters Dl, D2, and Bl are written over according to the following 
sequence . 

TEMP=D1/U 

D1=D2/U 

D2=TEMP 

B1«B2*U 

U-l . + (D1*B1*B1) / (D2*B2*B2) 
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Case 6: 

If, in either case 4 or 5, the updated parameters Dl and D2 have been 
rescaled below/above the window, 

{m) ** (-2) .LE.ABS (Dl) . LE. (m) **2 

(tfJ)**(-2) .LE*ABS(D2) »LE. (m)**2 

then the parameters Dl, Hll, H12, Bl and D2, H21, H22, respectively, are 

rescaled up/down by factors of m* Rescaling occurs as many times as 

necessary to bring Dl or D2 within the above window* If Dl and D2 are 

within the window on entry, rescaling occurs only once* 

Output parameters are 

PARAM(1)«-1. 

PARAM(2)=H11 

PARAM(3)=H21 

PARAM(4)=H12 

PARAM(5)=H22 

and Dl, D2, and Bl are written over by correctly scaled versions of case 
5 or 6. 

If D1<0, the matrix H=0 is generated (that is, %i=^i2 = ^21**' z 22 SB0 J 
PAJRAM(l) =-1, and the rest of the elements of PARAM contain zero. 

Case 7: 

If D2*B2=0 on entry, then H=l. Output is 
PARAM (1) --2. 0 only, 

APPLY MODIFIED GIVENS PLANE ROTATION 

SROTM applies the modified Givens plane rotation constructed by SROTMG, 
CALL SRQThi(n r 8x,incx,sy,iney r param) 
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computes 




h 21 h 22 



h 



[ 11 h 12 




i=l, . . .,n 



where the parameters Hll, H21, H12, and H22 are passed in the array PARAM 
according to the following schedule: PARAM (1) is the key parameter 
having values 1.0, 0.0, -1.0, or -2.0. 

Case for which PARAM (1) =1.0: 

H11=PARAM{2) 

H21=-1.0 

HI 2=1.0 

H22«PARAM(5) 
and PARAM (3) and PARAM (4) are ignored. 
Case for which PARAM (1) =0.0: 

Hll-1.0 

H21=PARAM(3) 

H12=PARAM{4) 

H22=1.0 

and PARAM (2) and PARAM (5) are ignored. 

Case for which PARAM (1) =-1.0 is rescaling case: 

H11=PARAM(2) 

H21»PARAM<3) 

H12=PARAM(4) 

H22=PARAM(5) 
is a full matrix multiplication. 
Case for which PARAM (1) =2.0 is H=l, namely: 

Hll=1.0 

H21=0.0 
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Hl2=0.0 
H22=a.O 

and PARAM(2) , PARAM(3), PARAM (4) , and PARAM{5) are ignored. If H=l, 
SROTM returns with no operation on input arrays sx, sy. 

If any other value for PARAM(l) is read (other than 1., 0, -1., -2.), 
SROTM aborts the job with the message: 

SROTM CALLED WITH INCORRECT PARAMETER KEY 
appearing in the logfile. 

The array PARAM must be declared in a dimension statement; 

DIMENSION PARAM (5) 

in the calling program. See the description of SROTMG for further 
details about the modified Givens transformation and the array PARAM, 

SCALE ARRAY 

These subroutines scale a vector. 

SSCAL computes 
X=aX 

where a is a real number and X is a real vector. 
Call from FORTRAN: 

CALL SSCAL {n 9 sa,sx, in OX) 

n Number of elements in vector 

sa Real scaling factor 

sx Real vector to be scaled 

incx Skip distance between elements of sx. For contiguous 

elements, incx-'L. 
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CSSCAL computes 
X=aX 

where a is a real number and X is a complex vector. 
Call from FORTRAN: 

CALL CSSCAL (n,sa, ex, inex) 

n Number of elements in vector 

sa Real scaling factor 

ex Complex vector to be scaled 

inex Skip distance between elements of ax* For contiguous 

elements , 

CSCAL computes 
Y=aY 

where a is a complex number and Y is a complex vector. 
Call from FORTRAN: 

CALL CSCAL {n,e<2, ex f inex) 

n Number of elements in vector 

ea Complex scaling factor 

ex Complex vector to be scaled 

inex Skip distance between elements of ex* For contiguous 

elements, incx=l* 

SWAP TWO ARRAYS 

These subroutines interchange two arrays. 
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SSWAP exchanges two real vectors. 
Call from FORTRAN: 



CALL SSWAP (n,sx 9 inex 9 8y f incy) 



n Number of elements in vector 

sx One real vector 

incx Skip distance between elements of sx. For contiguous 

elements , inco&l. 

sy Another real vector 

inoy Skip distance between elements of By. For contiguous 

elements, inoy**l. 



CSWAP exchanges two complex vectors. 
Call from FORTRAN: 

CALL CSWAP (rircx, inox 9 cy 9 inoy ) 



n Number of elements in vector 

ox One complex vector 

incx Skip distance between elements of ox. For contiguous 

elements, inox^X. 

oy Another complex vector 

inoy Skip distance between elements of oy. For contiguous 

elements , inoy-1* 



OTHER LINEAR ALGEBRA SUBPROGRAMS 

These linear algebra subprograms are extensions of the BLAS and conform 
to the same calling sequence. Table 4-2 contains the purpose, name, and 
type of each linear algebra subprogram. 
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SPARSE MATRIX PRIMITIVES 

This subroutine and function are useful primitives for the lower upper 
factorization and solution of sparse linear systems. 

SPAXPY is defined in FORTRAN in the following way* 

DO 10 1=1, N 
10 S Y ( INDEX (I) ) =SA*SX ( I ) +SY { INDEX (I) ) 

Call from FORTRAN: 

CALL SPAXPY {n f sa 9 sx, sy, index) 



n Number of elements in the vectors 

sa Real scalar multiplier 

sx Real vector operand 

sy Real vector operand 

index Vector of indexes 



SPODT is defined in FORTRAN in the following way. 

DO 10 1=1, N 
1 0 PDOT=PDOT+SY ( INDEX ( I ) ) *SX < I ) 

Call from FORTRAN; 

pdot^SVTxyv {n,sy, index, sx) 



n Number of elements in the vectors 

sy Real vector operand 

sx Real vector operand 

index Vector of indexes 
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Table 4-2. Other linear algebra subprograms 



Purpose 


Name (parameter list) 


Type 


Primitives for the LU 
factorization of sparse 
linear systems 


SPAXPY (n,sa,sx 9 sy 9 index) 
SPDOT (n 9 sy 9 index, sx) 


Routine 

Real function 


Index of element with 
maximum or minimum value 


ISMAX (n,sx, incx) 
ISMIN (n , sx, incx) 


Integer 
functions 


Index of element with 
minimum absolute value 


ISAMIN ( n , sx, incx) 


Integer 
function 


Sum the elements of a 
vector 


SSUM (n,sx, incx) 
CSJM {n , cx, incx) 


Real function 
Complex function 


Construct complex Givens 
plane rotation 


CROTG ( ca , cb 9 c c , cs ) 


Routine 


Apply complex Givens 
plane rotation 


CROT (n , cx, incx, cy , incy , 
cc,cs) 


Routine 


Cray machine constants 


SMACH (mack) 


Real function 



INDEX OF ELEMENT WITH MAXIMUM OR MINIMUM VALUE 

These integer functions find the first index of the largest or smallest 
element of a real vector, 

ISMAX returns the first index i such that 

|x A | =max|xj : j « l,...,n}« 
where x^ is an element of a real vector. 
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Call from FORTRAN : 



imax^lSMAX (n , sx,inox) 

n Number of elements to process in the vector to be searched 

(n=vector length if inco^X; n^vector length/2 if 
incx=2; etc,) 

sx Real vector to be searched 

inox Skip distance between elements of sx. For contiguous 

elements , incos*!* 

ISMIN returns the first index i such that 

|x^{=rain|xj : j=l, . . .n^. 
where Xj is an element of a real vector. 
Call from FORTRAN: 

imin= ISMIN (n, sx,incx) 

n Number of elements to process in the vector to be searched 

(^vector length if inoop*!; w=vector length/2 if 
incx=2} etc.) 

sx Real vector to be searched 

inox Skip distance between elements of sx. For contiguous 

elements, ineay=l m 

INDEX OF ELEMENT HAVING MINIMUM ABSOLUTE VALUE 

This integer function finds the first index of the smallest absolute 
value of the vector elements of a real vector. 

ISAMIN returns the first index i such that 

|xil=min||xj| ;j=l,...n}. 
where Xj is an element of a real vector. 
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Call from FORTRAN: 



imi 7i«lSAMiN (n , sx, inox) 

n Number of elements to process in the vector to be searched 

vector length if inos^lj ^vector length/2 if 
inox=2; etc.) 

sx Real vector to be searched 

inox Skip distance between elements of sx. For contiguous 

elements, incx±l. 

SUM OF THE VALUES 

These functions sum the elements of a real or complex vector. 

SSUM sums the elements of a real vector. 
Call from FORTRAN: 

suff^SSUM {n , sx, inox) 



n Number of elements in vector 

sx Real vector to be summed 

inox Skip distance between elements of sx. For contiguous 

e lement s , i nooF*l . 



CSUM sums the elements of a complex vector. 
Call from FORTRAN: 

swn=CSWl (n , ox, inox) 



n Number of elements in vector 

ox Complex vector to be summed 

inox Skip distance between elements of ox* For contiguous 

elements, ineo^l. 
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COMPUTE COMPLEX GIVENS PLANE ROTATION 

CROTG computes the elements of a complex Givens plane rotation matrix as 
in equation 9. 



Equation 9: 

(o / \-s c / \ b 
The 2x2 matrix is unitary and A and B are overwritten, 
Call from FORTRAN : 





CALL CROTG (oa , oh , o o f os ) 



oa Complex a of equation 9 

ob Complex b of equation 9 

oo Complex sine of equation 9 

ob Complex cosine of equation 9 



CONSTRUCT COMPLEX GIVENS PLANE ROTATION 

CROT applies the complex Givens plane rotation computed by the 
subroutine CROTG. It performs equation 10. 



Equation 10: 

')-(' s 

where x and y are complex row vectors. 
Call from FORTRAN: 




CALL CROT (n r ox, inox, oy ,inoy ,eo 9 o8) 
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n Number of elements in vector 

ox Complex vector to be modified 

inox Skip distance between elements of ex* For contiguous 

elements, incz?*!. 

ay Complex vector to be modified 

incy Skip distance between elements of oy. For contiguous 

elements, iney^l. 

00 Complex cosine of equation 10 

es Complex sine of equation 10 



CRAY MACHINE CONSTANTS 

In SMACH or CMACH, job is an integer argument and returns Cray 
machine constants as calculated by the FORTRAN version of SMACH or 
CMACH, (See the Basic Linear Algebra Subprograms for FORTRAN Usage by 
Chuck L. Lawson, Richard J, Hanson, Davis R, Kincaid, and Fred T* 
Crow, published by Sandia Laboratories, Albuquerque, 1977, publication 
number SAND77-0898. ) 

Call from FORTRAN: 



x=SMAOU job) 



SMACH returns the following information. 

for job=± 0.7105E-14 The machine epsilon (the smallest 

number € such that 1.+ € 7*1-) 
=2 •1290E-2449 A number close to smallest 

normalized, represen table number 
=3 .7750E+2450 A number close to largest normalized, 

representable number 

Otherwise, an error message is returned to the user's logfile* 

Call from FORTRAN; 



x=CMACH(job) 
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CMACH returns the following information. 

for job=l 0.7105E-14 The machine epsilon (the smallest 

number € such that 1.+ 6 7*1*) 
=2 .1348E1216 A number close to the square root of 

the smallest normalized, 
representable number 
=3 . 7421E+1217 A number close to the square root of 

the largest normalized, representable 
number 

Otherwise, an error message is returned to the user's logfile, CMACH 
(2) and CMACH (3) were chosen to prevent overflow and underflow during 
complex division. 



FUNCTIONS AND LINEAR RECURRENCE SUBROUTINES 

These subroutines solve first-order and some second-order linear 
recurrences, respectively. A linear recurrence uses the result of a 
previous pass through the loop as an operand for subsequent passes 
through the loop. Such use prevents vector izat ion. These subroutines 
can be used to optimize FORTRAN loops containing linear recurrences. 

F0LR solves first-order linear recurrences as in equation 11. 



Equation 11: 

c r= b i 

Ci=-aiCj^i+bi for i=2,3.„.,n 

or in FORTRAN, 

EQUIVALENCE (B,C) 
C(1)«B(1) 
DO 10 1=2, N 
10 C(I)«-A(I)*C(I-1)+B(I) 

Call from FORTRAN: 



CALL FOLR(rt,a,inca,btineb) 
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n Length of linear recurrence 

a Vector a of length n of equation 11. (A(l) is 

arbitrary.) 

inoa Skip distance between elements of the vector operand A, 

For contiguous elements, inoa*!, 

b Vector b of equation 11 on input and vector c of 

equation 11 on output. (The output overwrites the 
input. ) 

inob Skip distance between elements of the vector operand b 

and result C. For contiguous elements, inob=l m 

FOLRP solves first-order linear recurrences as in equation 12. 

Equation 12: 

ci«bx 

Cj^ajCj^i+bi for i~2,3...,n 

or in FORTRAN: 

EQUIVALENCE (B , C) 
C(1)=B(1) 
DO 10 1=2, N 
10 C(I)*A<I)*C(I-1)+B(I) 

Call from FORTRAN: 



CALL FOLRP (n,a r inoa, b,inab) 



n Length of linear recurrence 

a Vector a of length n of equation 12. (A{1) is 

arbitrary.) 

inoa Skip distance between elements of the vector operand 

a. For contiguous elements, inoa=l. 

b Vector b of equation 12 on input and vector c of 

equation 12 on output. (The output overwrites the 
input.) 

inch Skip distance between elements of the vector operand b 

and result o. For contiguous elements, inoh*\. 
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F0LR2 solves first-order linear recurrences as in equation 11, The 
solution, however, is written to a vector a, which is different from 
vector B in subroutine F0LR. 

Call from FORTRAN: 



CALL F0LR2 (n , a , inoa , b,inob 9 o 9 inoo) 



n Length of linear recurrence 

a Vector a of length n of equation 11. (A(l) is arbitrary.) 

inoa Skip distance between elements of the vector operand a. 

For contiguous elements, inea=l* 

b Vector b of equation 11 

inch Skip distance between elements of the vector operand b and 

result C. For contiguous elements, incb=l. 

e Vector o of equation 11 

inao Skip distance between elements of the vector result e. 

For contiguous elements, ine^l. 



F0LR2P is a combination of FOLRP and F0LR2. 
Call from FORTRAN : 



CALL F0LR2P {n,a,inoa 9 b 9 incb 9 c,inec) 



n Length of linear recurrence 

a Vector a of length n of equation 12 . (A(l) is 

arbitrary. ) 

inoa Skip distance between elements of the vector operand 

a. For contiguous elements, inoa^l m 

b Vector b of equation 12 on input 

ineb Skip distance between elements of the vector operand 

b m For contiguous elements, incb=l. 
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a Vector a of equation 12 

inoc Skip distance between elements of the vector result 
For contiguous elements, incc=l» 



FOLRN solves for the last term of a first-order linear recurrence. That 
is r n of 

r 1 =b 1 

r i 35 ~ a i r i-l +b i i*=2, 3, . . . r n 
Call from FORTRAN: 



resu 1 1- FOLRN (n,a,inca,b,incb) 



n Length of linear recurrence 

a Vector a of length n of equation 11. (A(l) is 

arbitrary.) 

inoa Skip distance between elements of the vector operand A. 

For contiguous elements , incc^l. 

b Vector b of length n of equation 11. (The output 

overwrites the input.) 

inch Skip distance between elements of the vector operand and 

result j&. For contiguous elements, incb*l. 



Example : 

This routine allows for efficient evaluation of polynomials using 
Horner's method. 

n 

Let p(x)=5 bix 11 - 1 
i=0 

then p (a) = (bQX+bj)x+b2)x+. . .b n ) Hornets rule. 
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In FORTRAN: 

PA=B(0) 

DO 10 I«1,N 

PA=PA*X+B(I) 
10 CONTINUE 

or equivalently 

PA=FOLRN(N+1,-X,0,B<0) ,1) • 

SOLR solves second-order linear recurrences as in equation 12, 

Equation 12: 

c i+2 =a i c i+l +b i c i for i=l#2.«. 

or in FORTRAN, 

DO 10 I«1,N 
10 C(I + 2)~A(I)*C(I+1)+B(I)*C(I) 

Call from FORTRAN: 

CALL SOLR(n,a,inca r b,incb,c,inee) 

n Length of linear recurrence 

a Vector a of length n of equation 12 

inoa Skip distance between elements of the vector operand A. 

For contiguous elements, inca=l. 

b Vector b of length n of equation 12 

inch Skip distance between elements of the vector operand B. 

For contiguous elements, inch**!* 

c Vector result C of length N+2 of equation 12 

inoa Skip distance between elements of the vector result C. For 

contiguous elements, incc^l. C(l) and C{2) are input to 
this routine; C(3) ,C(4) , . . • ,C(N+2) are output from this 
routine. 
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SOLRN solves for only the last term of a second-order linear recurrence, 
that is c(n) of SQlR(n,a,inca f b,incb 9 c,inec) • SOLRN is a real function* 

Call from FORTRAN: 



result ■= SOLRN (n , a , inea ,b 9 inob ,c 9 incc) 



n Length of linear recurrence 

a Vector A of length N of equation 12 

inoa Skip distance between elements of the vector operand A. 

For contiguous elements, inoa-1. 

b Vector B of length N of equation 12 

incb Skip distance between elements of the vector operand B* 

For contiguous elements, incb~l. 

e Vector result C of length N+2 of equation 12 

inco Skip distance between elements of the vector result C. For 

contiguous elements, inec=l* C(l) and 0(2) are input to 
this routine; C(3) ,C(4) ,. ,C(N+2) are output from this 
routine • 

The FORTRAN loop 

R1«C(1) 
R2=C(2) 
DO 10 1*1, N-2 
TEMP=R2 

R2=A(I)*R2+B(I)*R1 
R1=TEMP 
10 CONTINUE 
RESULT»R2 

could be solved as follows • 



result-SOLBN (n ,a , 1 , b , 1 ,c ) 
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Example : 



SOLRN might be used to find r n of the calculation 



with the following call. 



im= SOLRN (n,a,l,b, 1,<?,1) 



The equivalent FORTRAN follows. 

R1=C(1) 
R2=C(2) 
DO 10 I»1,N 
TEMP=R2 

R2=A(I)*R2+B(I)*Rl 
Rl^TEMP 
10 CONTINUE 
RN=R2 



SOLR3 computes a second-order linear recurrence of three terms , that is 



c l =c l 
c 2 =c 2 

c i" c i +a i-2 c i-l +b i-2 c i-2 1=3 



Call from FORTRAN; 



CALL SOLR3 (n , a , inoa , b , in eb, a , inoc) 



n 



Length of linear recurrence 



a 



Vector A of length N of equation 12 



inoa 



Skip distance between elements of the vector operand A. 
For contiguous elements, inoa^X. 



b 



Vector b of length n of equation 12 
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inch 



Skip distance between elements of the vector operand b. 
For contiguous elements, incb=l. 



a Vector result c of length n+2 of equation 12 

ineo Skip distance between elements of the vector result o m 

For contiguous elements, e(l) and o(2) are 

input to this routine; c{3) , o(A) , • . . , e{n+2) are 
output from this routine. 



Example : 

S0LR3 solves a system of lower bidiagonal linear equations Lx=b. 



Lx- 



1 0 0 0, 
e 1 1 0 0. 
f x e 2 1 ( 



0 f- 



1 0 . 

^3^4 1 0 



i0 0 0 



n \ 



f n-2 e n-l 1 



/5\ 



\ 



/ 



= b 



then there is 



x 2 =b 2 -e 1 x 1 

x i =b i~ e i-l x i-l- f i-2 x i-2 



Given this problem, it can be solved with the following FORTRAN. 



DO 10 1=1, N-l 
10 E(I)=-E(I) 

DO 20 1=1, N- 2 
20 F(I)=-F(I) 



B(1)=B(1) 

B(2)=B(2)+E(1)*B(1) 

CALL SOLR3(N,E(2),l,F(l),l,B(l),l) 
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SINGLE-PRECISION REAL AND COMPLEX LINPACK ROUTINES 



LINPACK is a package of FORTRAN routines that solve systems of linear 
equations and compute the QR, Cholesky, and singular value 
decompositions. The original FORTRAN programs are documented in the 
LINPACK User's Guide by J, J* Dongarra, C. B. Moler, J. R. Bunch, and G. 
W, Stewart, published by the Society for Industrial and Applied 
Mathematics (SIAM) , Philadelphia, 1979, Library of Congress catalog card 
number 78-78206. 

Each single-precision $SCILIB version of the LINPACK routines has the 
same name, algorithm, and calling sequence as the original version. 
Optimization of each routine includes the following: 

• Replacement of calls to the BLAS routines SSCAL, SCOPY, SSWAP, 
SAXPY, and SROT with in-line FORTRAN code that the CFT compiler 
vectorizes 

• Removal of FORTRAN IF statements if the result of either branch 
is the same 

• Replacement of SDOT to solve triangular systems of linear 
equations in SGESL, SPOFA, SPOSL, STRSL, and SCHDD with more 
vector izable code 

These optimizations affect only the execution order of floating-point 
operations in modified DO-loops. Refer to the LINPACK User's Guide 
for further descriptions. The complex routines have been added 
without much optimization. 

Table 4-3 contains the name, matrix, and purpose of each LINPACK 
routine in $SCILIB, 



SINGLE-PRECISION EISPACK ROUTINES 

EISPACK is a package of FORTRAN routines for solving the eigenvalue 
problem, computing and using the singular value decomposition, and 
solving banded symmetric systems of linear equations. 

The original FORTRAN versions are documented in the Matrix Eigensystem 
Routines - EISPACK Guide, second edition by B. T. Smith, J. M. Boyle, 
J, J. Dongarra, B. S. Garbow, Y. Ikebe, V. C. Klema, and C. B. Moler, 
published by Springer-Verlag, New York, 1976, Library of Congress 
catalog card number 76-2662; and in the Matrix Eigensystem Routines - 
EISPACK Guide Extension by B. S. Garbow, J. M. Boyle, J, J. Dongarra, 
and C. B. Moler, published by Springer-Verlag, New York, 1977, Library 
of Congress catalog card number 77-2802. 
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Table 4-3. Single-precision LINPACK routines 



Name 



Matrix or 
Decomposition 



Purpose 



SGECO 
SGEFA 
SGESL 
SGEDI 

CGECO 
CGEFA 
CGESL 
CGEDI 

SGBCO 
SGBFA 
SGBSL 
SGBDI 

CGBCO 
CGBFA 
CGBSL 
CGBDI 



SPOCO 
SPOFA 
SPOSL 
SPODI 

CPOCO 
CPOPA 
CPOSL 
CPODI 



Real general 



Complex general 



Real general banded 



Complex general banded 



Factor and estimate condition 

Factor 

Solve 

Compute determinant and inverse 

Factor and estimate condition 

Factor 

Solve 

Compute determinant and inverse 

Factor and estimate condition 

Factor 

Solve 

Compute determinant 

Factor and estimate condition 

Factor 

Solve 

Compute determinant 



Real positive definite 



Factor and estimate condition 

Factor 

Solve 

Compute determinant and inverse 



Complex positive definite Factor and estimate condition 

Factor 
Solve 

Compute determinant and inverse 



SPPCO 
SPPFA 
SPPSL 
SPPDI 

CPPCO 
CPPFA 
CPPSL 
CPPDI 



Real positive definite 
packed 



Complex positive 
definite packed 



Factor and estimate condition 

Factor 

Solve 

Compute determinant and inverse 

Factor and estimate condition 

Factor 

Solve 

Compute determinant and inverse 
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Name 


Matrix or 

ueuompusi u ion 


Purpose 


SPBCO 
SPBFA 
SPBSL 
SPBDI 


Real positive definite 
banded 


Factor and estimate condition 

Factor 

Solve 

Compute determinant 


CPBCO 
CPBFA 
CPBSL 
Ci J BDI 


Complex positive 
definite banded 


Factor and estimate condition 

Factor 

Solve 

Compute determinant 


SSICO 
SS IFA 
SSISL 
SSIDI 


Symmetric indefinite 


Factor and estimate condition 

Factor 

Solve 

Compute inertia , determinant, and 
inverse 


CHICO 
CHIFA 
CHISL 
CHIDI 


Hermitian indefinite 


Factor and estimate condition 

Factor 

Solve 

Compute inertia, determinant, and 
inverse 


SSPCO 
SSPFA 
SSPSL 
SSPDI 


Symmetric indefinite 
packed 


Factor and estimate condition 

Factor 
Solve 

Compute inertia, determinant, and 
inverse 


CHPCO 
CHPFA 
CHPSL 


Hermitian indefinite 
packed 


Factor and estimate condition 

Factor 

Solve 

f*V"MTiT"i n ^ 1 nArf i s rlaf o t"tti "i YiAttf" ~ anH 

inverse 


STRCO 
STRSL 
STRDI 


Real triangular 


Factor and estimate condition 
Solve 

Compute determinant and inverse 


CTRCO 
CTRSL 
CTRDI 


Complex triangular 


Factor and estimate condition 
Solve 

Compute determinant and inverse 
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Table 4-3. Single-precision LINPACK routines (continued) 



Name 


Matrix or 
Decomposition 


Puroose 


SGTSL 


Real tridiagonal 


Solve 


CGTSL 


ComDlex tridiaoonal 


Solve 


SPTSL 


Real positive definite 
tridiagonal 


Solve 


CPTSL 


Complex 


Solve 


SCHDC 
SCHDD 
SCHUD 
SCHEX 


Real Cholesky 
decompos i t ion 


Decompose 
Downdate 
Uodate 
Exchange 


CCHDC 
CCHDD 
CCHUD 
CCHEX 


Complex Cholesky 
decomposition 


Decompose 
Downdate 
Update 
Exchange 


SQRDC 
SQRSL 


Real 


Orthogonal factorization 
Solve 


CQRDC 
CQRSL 


Complex 


Orthogonal factorization 
Solve 


SSVDC 
CSVDC 


Real 
Complex 


Singular value decomposition 



Each $SCILIB version of the EISPACK routines has the same name, algorithm, 
and calling sequence as the original version. Optimization of each 
routine includes the following. 

• Use of the BLAS routines SDOT, SASUM, SNRM2, ISAMAX, and ISMIN 
when applicable 

# Removal of FORTRAN IF statements if the result of either branch 
is the same 
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• Unrolling complicated FORTRAN DO-loops to improve vectorization 

• Use of the CFT compiler directive CDIR$ IVDEP when no dependencies 
exist that prevent vectorization 

These modifications increase vectorization and, therefore, reduce 
execution time. Only the order of computations within a loop is changed; 
the modified versions produce the same answers as the original versions 
unless the problem is sensitive to small changes in the data. 

Table 4-4 contains the name and purpose of each EISPACK routine in $SCILIB. 



Table 4-4. Single-precision EISPACK routines 



Name 


Matrix or 


Purpose 




Decomposition 




CG 


Complex general 




CH 


Complex symmetric 




RG 


Real general 


Find eigenvalues and eigenvectors 


RGG 


Real general generalize 


(as desired) 




AX= \Bx 




RS 


Real symmetric 




RSB 


Real symmetric band 




RSG 


Real symmetric generalize 






hx- XBx 




RSGAB 


Real symmetric generalize 






KBX= Xx 




RSGBA 


Real symmetric generalize 






BAx= Xx 




RSP 


Real symmetric packed 




RST 


Real symmetric 






tridiagonal 




RT 


Special real 






tridiagonal 




BALANC 


Real general 


Balances matrix and isolates 






eigenvalues whenever possible 


CBAL 


Complex general 
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Table 4-4. Single-precision EISPACK routines (continued) 



Name 


Matrix or 
jjecompos x x. xon 


Purpose 


ELMHES 
ORTHES 

COMTH 


Real general 

WwuipXcX ^uncial 


Reduce matrix to upper Hessenberg 
form 


ELTRAN 
ORTRAN 


Real general 


Accumulate transformations used in 
the reduction to upper Hessenberg 
form done by ELMHES, ORTHES 


BALBAK 
ELMBAK 
ORTBAK 

COMBAK 

CORTB 

CBABK2 

REBAKB 


Real general 
Complex general 


Form eigenvectors by back 
transforming those of the 
corresponding matrices determined by 
BALANC, ELMHES, ORTHES, C0MMES, 
C0RTH, and CBAL 


TREDl 
TRED2 
TRED3 


Real symmetric 


Reduce to symmetric tridiagonal 


TRBAK1 
TRBAK3 


Real symmetric 


Form eigenvectors by back 
transforming those of the 
corresponding matrices determined 
by TREDl or TRED3 


IMTQLV 
IMTQL2 


Symmetric tridiagonal 


Find eigenvalues and/or 
piapnvectors bv imolicit OL method 


RATQR 


Symmetric tridiagonal 


Find the smallest or largest 
eigenvalues by rational QR method 
with Newton corrections 
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Table 4-4. Single-precision EISPACK routines (continued) 



Name 


Matrix or 
Decomposition 


Purpose 


TQLRAT 

TQL1 

TQL2 


Symmetric tridiagonal 


Find the eigenvalues by rational 
QL method 

Find the eigenvalues and/or 
eigenvectors by the rational QL or 
OL inpfchod 


BISECT 
TRIDIB 
TSTURM 
TINVIT 


Symmetric tridiagonal 


Find eigenvalues and/or eigen- 
vectors which lie in a specified 
interval using bisection and/or 
inverse iteration 


FIGI 
FIGI2 


Nonsvmme tr ic 
tridiagonal 


Reduce to svironetric fcridiaaonal 
with the same eigenvalues 


BAKVEC 


Nonsymmetric 


Form eigenvectors by back 
transforming corresponding matrix 

dp'hiirininpd hv P*T£»T 


HQR 
HQR2 
CQMOR 
C0MQR2 


Real upper Hessenberg 
ComDlex uDDer Hessenbera 


Find eigenvalues and/or 
eigenvectors by QR method 


INVIT 
CINVIT 


Complex upper Hessenberg 


specified eigenvalues 


BANDR 


Real symmetric banded 


Reduce to a symmetric tridiagonal 
matrix 


BANDV 


Real symmetric banded 


Find those eigenvectors 
corresponding to specified 
eigenvalues using inverse iteration 
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Table 4-4. Single-precision EISPACK routines (continued) 



Name 


Matrix or 
Decompos i t ion 


Purpose 


BQR 


Real symmetric banded 


Find eigenvalues using QR algorithm 
with shifts of origin 


MINFIT 


Real rectangular 


Determine the singular value 
decomposition A=USV T , forming U T B 
rather than U. Householder 
bidiagonalization and a variant of 

4- Vs e» ITD 34 T as^r i 4* Htd it d nca/^ 
uiic? yrs. ai^UL x uiiiu ale uocu* 


SVD 


Real rectangular 


Determine the singular value 
decomposition A=USV T * Householder 
bidiagonalization and a variant of 
trie yjtv axgoritnm are useu • 


HTRIBK 
HTRIB3 
HTRIDI 


Complex Hermitian 


All eigenvalues and eigenvectors 


QZHES 
QZIT 
QZVAL 
QZVEC 


Real generalize 
eigenproblem hx m A Bx 


All eigenvalues and eigenvectors 


COMLR 

C0MLR2 

REDUC 

REDUC2 


Complex general 

Real symmetric generalize 
Ax= A Bx 

Real symmetric generalize 
ABx= A Bx or BA^= A Bx 


Reduce matrix to upper Hessenberg 

> Transforms generalize 

symmetric eigenproblems to standard 
i symmetric eigenproblems 
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MATRIX INVERSE AND MULTIPLICATION ROUTINES 



The matrix inverse subroutine, MINV, computes the matrix inverse and 
solves systems of linear equations using the Gauss-Jordan elimination. 
MXM and MXMA are two optimal matrix multiplication routines, one more 
general than the other. MXV and MXVA are similar to MXM and MXMA, 
respectively; however, MXV and MXVA handle the special case of matrix 
times vector. 

MINV computes the determinant and inverse of a square matrix. MINV can 
also solve several systems of linear equations described by one square 
matrix and several right-hand sides. 

Call from FORTRAN: 



CALL MINV (ab,n,nd, scratch, det,eps,m, mode) 



ab Augmented matrix of the square matrix a and the n x m 

matrix b of the m right-hand sides for each system of 
equations to solve. The solution overwrites the 
corresponding right-hand side* In the calling routine, 
ab must be dimensioned a(nd 9 n+m) . 

n Order of matrix a 

nd Leading dimension of ab 

scratch User-defined working storage array of length at least 2*w 

det Determinant of matrix a 

eps User-defined tolerance for the product of pivot elements 

m >0 Number of systems of linear equations to solve 

=0 Determinant of a is computed, depending on the value 
of MODE. 

mode +1 a is overwritten with 

-0 a is not saved and a*" 1 is not computed. 



MXM computes a matrix times matrix product (c=ab) and assumes a skip 
distance between elements of the matrices to be 1. 



Call from FORTRAN: 



CALL MXM(a 9 nar 9 b 9 nac 9 c 9 nbe) 
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a First matrix of product 

nav Number of rows of matrices a and e 

b Second matrix of product 

nae Number of columns of matrix a and the number of rows of 
matrix b 

c Result matrix 

nbc Number of columns of matrices b and e 



MXV computes a matrix times a vector and assumes a skip distance between 
elements of the matrix to be 1. 

In FORTRAN, MXV would perform the following calculations. 

DO 10 1=1, NAR 
10 C(I)=A(I r l)*B(l)+A(I # 2)*B(2)+...+A(I r NBR)*B(NBR) 

Call from FORTRAN: 

CALL MXV(a,nar,b,nbr) 



a Matrix of product 

nar Number of rows of matrices a and o 

b Vector of product 

nbr Number of elements of vector b and the number of columns of 

matrix a 

c Resulting vector 



MXMA computes a matrix times matrix product {c=ab) and allows for 
arbitrary spacing of matrix elements* 

Call from FORTRAN: 

CALL mxma {a,na,iad 9 b, nb, ibd, e, ne,icd,nar, nae, nbe) 
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a First matrix of product 

na Spacing between column elements of a 

iad Spacing between row elements of a 

b Second matrix of product 

nb Spacing between column elements of b 

ibd Spacing between row elements of b 

o Output matrix 

no Spacing between column elements of a 

iod Spacing between row elements of e 

nap Number of rows in first operand and result 

nae Number of columns in first operand and number of rows in 
second operand 

nbe Number of columns in second operand and result 



Example 1: 

The dimensions of matrix A below are 3x3. Consider the 2x3 submatrix A 1 
marked by asterisks. 



(1,3>* 

(2,3) 

(3,3)* 



The row spacing of A* (iad) is defined as the length of the path 
through A between two consecutive row elements of A 1 . In this example, 
the path is (a) through (c) (iad**3) . 

The column spacing of A' (na) is defined as the length of the path 
through A between two consecutive column elements of A'. In this 
example, the path is (a) through (b) (na=2) ? the number of rows of A 1 
is 2 (nar=2) ; and the number of columns of A* is 3 (na<^3) • 
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Example 2; 



Consider the matrices below. Let A T r the transpose of A equal the 
first operand of a matrix multiply operand* The transpose of a matrix 
has as its ith row the ith column of the original matrix. 



(1,1) v(l,2) (1,3) (1,1) M2,l) M3,l) 

| (a) /(c) (a) ^^JM^^^ 

(2,1) / (2,2) (2,3) (1,2)^^^272) (3,2) 

(3,1)/ (3,2) (3,3) (1,3) (2,3) (3,3) 



Matrix A Matrix A T 

The length of the path between two consecutive column elements of A T is 
the same as the length of the path between two consecutive row elements 
of A. Refer to paths (a) through (c) of both matrices (na=3) . The 
length of the path between two consecutive row elements of A^ is the 
length of the path between two consecutive column elements of A. This 
path consists of just (a) (iad=l) . In this example nar**3 and nac=3. 

Therefore, if A is the first operand of a call to MXMA, the following 
subroutine call is used. 



CALL MXMA(A r l,3,...) 



If A 1 is the first operand of a call to MXMA/ the following subroutine 
call is used. 



CALL MXMA(A,3,1,...) 



MXVA computes a matrix times a vector and allows for arbitrary spacing of 
matrix elements. 

Call from FORTRAN: 



CALL MXVh(a,na,iad,b,nb,c,nc,nar,nbr) 



a First matrix of product 

na Spacing between column elements of a 

iad Spacing between row elements of a 
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b 



Vector of product 



nb 



Spacing between elements of h 



o 



Result vector 



no 



Spacing between elements of o 



nav 



Number of rows in first operand and number of elements in 
the result 



nbv 



Number of columns in first operand and number of elements 
in the second operand 



FAST FOURIER TRANSFORM ROUTINES 

These routines apply a Fast Fourier transform. Each routine can compute 
either a Fourier analysis or a Fourier synthesis. Detailed descriptions, 
algorithms, performance statistics, and examples of these routines appear 
in the Complex Fast Fourier Transform Binary Radix Subroutine (CFFT2) , 
CRI publication SN-0203? Real to Complex Fast Fourier Transform Binary 
Radix Subroutine (RCFFT2) , CRI publication SN-0204; and Complex to Real 
Fast Fourier Transform Binary Radix Subroutine (CRFFT2) , CRI publication 
SN-0206. 

Each routine has the same argument list: (init, ix, n 9 x, wovk, y) . 



init 


Initialization flag 


ix 


Analysis/synthesis flag 


n 


Size of transform 


X 


Input vector 


work 


Working storage vector 


y 


Result vector 



The routines are called the first time with initio and n as a power 
of two in order to initialize the needed sine and cosine tables in the 
working storage area work. Then for each input vector of length n 
(length {n/2)+l for CRFFT2) , each routine is called with initio. The 
sign of IX determines whether a Fourier synthesis or a Fourier analysis 
is computed. If the sign of ix is negative, a synthesis is computed; 
if positive, an analysis is computed. Table 4-5 shows the size and 
formats of x f y, and work for each routine. 
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Table 4-5. Arguments for Fourier transform routines 



Argument 


CPPT2 


RCPPT2 


CRFFT2 


X 


Complex n 


Real n 


Complex 
(«/2)+l 


work 


Complex 
(5/2) n 


Complex 
(3/2) n+2 


Complex 
(3/2) n+2 


y 


Complex n 


Complex 
(n/2)+l 


Real n 



CFFT2 calculates equation 13. 



Equation 13: 

n-1 

y k = 2 Xj exp(+ lii jk) 
j«0 n 

for k=0, 1, • . • ,n-l 

where x A i=0,l, . . . ,n-l are stored in X(I),3>1,N 
i~0, 1, ♦ ..,n-l are stored in Y(I),I=1,N 
and the sign of the exponent is determined by SIGN(IX). 
Call from FORTRAN: 



call CFFT2 {init ,ix f n 9 x 9 wovk,y) 



init Generates sine and cosine tables in work 

~0 Calculates Fourier transforms using sine and cosine 
tables of previous call 

ix >0 Calculates Fourier analysis 

<0 Calculates Fourier synthesis 

n Size of Fourier transform? 2 m where 3^m for the 

CRAY XHMP and 2<m for the CRAY-1 . 
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x Input vector. Vector of n complex values. 

Range: 10 2466 /^( t)>n* (1<T 24 * 6 ) for 

work Working storage. Vector of (5/2) n complex values. 

y Result vector. Vector of n complex values. 



NOTE 

The input vector x can be equivalenced to either y 
or work} then the input sequence is overwritten. 



RCPFT2 calculates 
n-1 

y k =2 2 Xj exp(+ 2JLL jk) 
j=0 n 

for k « 0,1,..., (n/2) 

where i=0,l, . . . ,n-l are stored in X(I),I=1,N 

y A i=0,l,...,n/2 are stored in Y(I) ,1*1, <N/2)+l 

and the sign of the exponent is determined by SIGN(IX). 

Call from FORTRAN: 



CALL RCFFT2(init,ix,n,x,work,y) 



init fO Generates sine and cosine tables in work 

=0 Calculates Fourier transforms using sine and cosine 
tables of previous call 

ix >0 Calculates Fourier analysis 
<Q Calculates Fourier synthesis 

n Size of Fourier transform? 2 m where 3<m. 

x Input vector. Vector of n real values 
Range: 10 2466 /2*?i>/c(i)^2*r2*10^ 2466 7 i=l,n. 

work Working storage. Vector, (3/2)rz+2 complex value. 

y Result vector* Vector of (t?/2)+1 complex values. 
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CRFFT2 calculates equation 13 where the Xi elements are complex and 
Xj=x n _j for j=0,l, . (n/2) . Only the first (n/2)+l elements are 
stored in X. 



Equation 13: 
n-1 

y k = 5 xj exp(+ 1*1 jk) 
j«0 n 

for k=0,l, . . . ,n-l 

where the xj elements are complex and are related by xj=x n _j 

for j=l,2,3, . . ., (n/2) 
Call from FORTRAN: 



CALL CBFFT2(init r ix r ntX,work,y) 



init j£Q Generates sine and cosine tables in work 

=0 Calculates Fourier transforms using sine and cosine 
tables of previous call 

ix >0 Calculates Fourier analysis 
<0 Calculates Fourier synthesis 

n Size of Fourier transform; 2 m where 3<p. 

x Input vector. Vector of (n/2)+l complex values 
Range: 10 2466 /n>x(i) >n*1(T 2466 ; i=l,?n 

work Working storage. Vector, (3/2) n+2 complex values. 

y Result vector. Vector of n real values. 



FILTER SUBROUTINES 

These subroutines are intended for filter analysis and design. They 
also solve more general problems. For detailed descriptions, 
algorithms, performance statistics, and examples, see Linear Digital 
Filters for CFT Usage, CRI publication 2240210. 
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FILTERG computes a convolution of two vectors. 



Given : 

(a^) i=l m Filter coefficients 

(dj) j-l,....,n Data 

FILTERG computes the following ♦ 
m 

o^~ % ajd^ + j_^ i=l,... r n~m + 1 

j=l 

Call from FORTRAN: 



CALL FILTERG {CL 9 m,d f n f O) 



a Vector of filter coefficients 

m Number of filter coefficients 

d Input data vector 

n Number of data points 

o Output vector 



FILTERS computes the same convolution as FILTERG except that it assumes 
the filter coefficient vector is symmetric. 

Given: 

(c^) i=l,«... r [m/2l ([m/2l=m/2 for m even and 
(d£) j=l n (m+l)/2 for m odd, called the 

ceiling function.) 

FILTERS computes the following. 

(m-l)/2 

m odd: o- 5 a j < d i+j-l +d i+m-j> 

+a rm1 * d i-tfTTi 1 i=l, ♦ . . ,n-m+l 



in • 



m even: o^= 



m/2 

2 aj( d -j+i-i + d ± + m _j) i=l,...,n-m+l 
j-1 
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Call from FORTRAN: 



CALL FILTERS (a,m r d f n f O) 



a Symmetric filter coefficient vector 

m M is formally the length of vector A but because A is 

symmetric (ai s am-i+l* only m/2 elements 

of A are ever referenced, 

d Input data vector 

n Number of data points 

o Output vector 



OPFILT computes the solution to the Weiner-Levinson system of linear 
equations Ta=b where T is a Toeplitz matrix in which elements are 
described by the following. 

tij=R(k) for |j-i|+l=k 

and k=l,...,n. 

Call from FORTRAN: 



CALL OPFILT {m,a t b,e,r) 



m Order of system of equations 

a Output vector of filter coefficients 

b Information auto-correlation vector 

o Scratch vector of length 2m 

2* Signal auto-correlation vector 



NOTE 

Although OPFILT solves this matrix equation faster than 
Gaussian elimination, OPFILT does no pivoting. 
Therefore , it is less numerically stable than Gaussian 
elimination unless the matrix T is positive, definite, 
or diagonally dominant* 
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Example : 



The following system of linear equations can be solved with the call 
OPFILT (3,A,B,C,R). The array C is one dimension with a length of at 
least six. (The t^j elements show how the numbers for R are obtained.) 

'R(l) R(2) R(3) 
R(2) R(l) R(2) 
^R(3) R<2) R(l) 

fc ll fc 12 ^3 
t21 fc 22 *23 
^31 fc 32 *33 





GATHER f SCATTER ROUTINES 

These subroutines allow the user to gather a vector from a source vector 
or to scatter a vector into another vector. A third vector of indexes 
determines which elements are accessed or changed. 

GATHER is defined in the following way. 

a^-b^ where i=l,... # n 
J i 

In FORTRAN: 

A (I) =B (INDEX (I)) 
where I B l f N 
Call from FORTRAN: 

CALL GATHER {n 9 CL 9 b 9 index) 

n Number of elements in each vector 

a Output vector 

b Source vector 

index Vector of indexes 
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SCATTER is defined in the following way, 
=bi where i=l,..,,n 

J i 

In FORTRAN: 

A(INDEX(I))=B(I) 
where 1=1 f N 
Call from FORTRAN : 

CALL SCATTER (n f a 9 index, b) 

n Number of elements in each vector 

a Output vector 

b Source vector 

index Vector of indexes 



SEARCH ROUTINES 

Several search routines in $SCILIB have been optimized in CAL. These 
routines use the vector units and vector mask to quickly find the number 
or positions of true occurrences in a vector of a given relation. The 
routines ILLZ and IILZ find the first occurrences, ILSUM counts the 
number of such occurrences. 

Several routines find the positions of a searched for object in a 
vector. These include; ISRCHEQ, ISRCHNE , ISRCHFLT, ISRCHFLE, ISRCHFGT , 
ISRCHFGEf ISRCHILT, ISRCHILE, ISRCHIGT f and ISRCHIGE. 

The following routines return an indexed array of all positions of an 
object within a vector. These include: WHENEQ, WHENNE, WHENFLT, 
WHENFLE, WHENFGT , WHENFGE, WHENILT, WHENXLE, WHENIGT, and WHENIGE. 

The OSRCHI and OSRCHF routines search ordered arrays for targets. 
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NUMBER OR SUM OF VALUES WITHIN A VECTOR OR BEFORE AN ELEMENT 

IILZ returns the number of zero values before the first nonzero value in 
an array. When scanning backward (incl < 0) , this routine starts at 
the end and moves backward (L(N) ,L(N + INCL) ,L(N + 2*INCL) , . . . ) . 

Call from FORTRAN: 



kount-llhZ (n,l 9 inol) 



n Number of elements to process in the vector (N=vector 

length, if incV=l; ^vector length/2, if incl~2; etc.) 

I Vector operand 

incl Skip distance between elements of the vector operand. For 

contiguous elements, in<?Z=l. 



ILLZ returns the number of false values preceding the first true value in 
a logical vector. When used with an integer or real vector, ILLZ returns 
the number of positive or zero values preceding the first negative 
value. When scanning backward (inel<0) , this routine starts at the end 
and moves backward (L(N) ,L(N+INCL) ,L(N+2*INCL) ,...). 

Call from FORTRAN: 



kount^iLLZ (n,l 9 incl) 



n Number of elements to process in the vector (n^vector 

length, if incfcl; ??*vector length/2, if incl=2; etc.) 

I Vector operand 

incl Skip distance between elements of the vector operand. For 

contiguous elements, incl-1. 



ILSUM counts the total number of true values in a vector declared 
LOGICAL. It counts the total number of negative values in a vector 
declared REAL or INTEGER. 

Call from FORTRAN: 



kount- ILSUM (n , I , incl ) 
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n Number of elements to process in the vector {^=vector 

length , if inet^l; n=vector length/2, if incl^2; etc.) 

I Vector operand 

inol Skip distance between elements of the vector operand. For 

contiguous elements, inol^l* 



SEARCHING FOR AN OBJECT IN A VECTOR 

These functions return the first location in an array that has a true 
relational value to the target. See table 4-6 for a summary. 



Table 4-6. ISRCH routines 



Name {parameter list) 


Description 


ISRCHEQ (n, array ,inc, target) 


Returns the first location in a real 
array that is equal to the real 
target 


ISRCHNE (n , array Ane , target) 


Returns the first location in a real 
array that is not equal to the real 
target 


ISRCHFLT (n , array 9 ine w target) 


Returns the first location in a real 
array that is less than the real target 


ISRCHFLE (n f array , ine , target ) 


Returns the first location in a real 
array that is less than or equal to the 
real target 


I SRCHFGT (n f array , ine, target) 


Returns the first location in a real 
array that is greater than the real 
target 


ISRCHFGE (n, array , ine, target) 


Returns the first location in a real 
array that is greater than or equal to 
the real target 
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Table 4-6 • ISRCH routines (continued) 



Name (parameter list) 


Description 






Keturns tne nrsc locauion in an 
integer array that is equal to the 
integer target 




TOD^UXTT? / v} A /"> »va/T7 7 1* vi/n -f~ sy vi sy /3 ~h \ 
XOXv^rUNi-i \ 71 jr l*(JLI*I*Lllj j> LrlO f £. UCIT'Q &l> ) 


Returns the first location in an 
integer array that is not equal to 
integer target 


the 


TQRf HTT/P f n A n y>y>/7 1 J 4yif* A ~h/iY*n0i~\ 

l^IxVllliJi. t'C*/ lKJ.tf j uiIKj> j L LfLLI t/& Is f 


Returns the first location in an 
integer array that is less than the 
integer target 




Returns the first location in an 
integer array that is less than or 
to an integer target 


equal 


ISRCHIGT (n,iarray ,ino, itarget) 


Returns the first location in an 
integer array that is not equal to 
integer target 


an 


ISRCHIGE , iarray , ine, itarget) 


Returns the first location in an 
integer array that is not equal to 
integer target 


an 



ISRCHEQ is used when a real array element is equal to a real target, or 
an integer array is equal to an integer target, ISRCHEQ replaces the 
I SEARCH routine but has an entry point of I SEARCH as well as ISRCHEQ. 

Call from FORTRAN: 



location^ ISRCHEQ (n , array , ino, target) 
loeation=lSRCHEQ(n, iarray, ino, itarget) 



n Number of elements to be searched* If n^O, then 0 is 

returned, 

array First element of real array to be searched 

iarray First element of integer array to be searched 

ino Skip distance between elements of the searched array 
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target Real value searched for in array. If target is not 
found r then the returned value is n¥l 9 

itavget Integer value searched for in array 

The FORTRAN equivalent follows. 

FUNCTION I SRCHEQ ( N , ARRAY , INC , TARGET ) 

DIMENSION ARRAY (N) 

J=l 

If (INC.LT.Q) J=N*(-INC) 
DO 100 I«1.N 

IF (ARRAY (J) .EQ. TARGET) GO TO 200 
J=J+INC 
100 CONTINUE 
200 ISRCHEQ=I 
RETURN 
END 



ISRCHNE is used when the array element (real or integer) is not equal to 
the target (real or integer). 

Call from FORTRAN: 



location = ISRCHNE {n , array ,ina, target ) 
location* ISRCHNE [n,iarray, inc 9 itarget) 



n Number of elements to be searched. If n<0, then 0 is 

returned. 

array First element of real array to be searched 

iarray First element of integer array to be searched 

inc Skip distance between elements of the searched array 

target Real value searched for in array. If target is not 
found f then the returned value is n+1. 

itarget Integer value searched for in array. 



ISRCHFLT is used when the real array element is less than the real target. 
Call from FORTRAN: 



location-ISRCKFL? (n , array, inc, target) 
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n Number of elements to be searched. If n<0, then 0 is 

returned. 

array First element of real array to be searched 

ine Skip distance between elements of the searched array 



target Real value searched for in array. If target is not 
found, then the returned value is rH-1. 

ISRCHFLE is used when the real array element is less than or equal to the 
real target. 

Call from FORTRAN: 

loeation=lSRCHFLE (n f array 9 ine, target) 



n Number of elements to be searched. If n£0, then 0 is 

returned. 

array First element of real array to be searched 

ine Skip distance between elements of the searched array 



target Real value searched for in array. If target is not 
found, then the returned value is rH-1. 

ISRCHFGT is used when the real array element is greater than the real 
target. 

Call from FORTRAN: 



loeation<*ISRCWPG? (n, array 9 ine , tar get) 



n Number of elements to be searched. If n<0, then 0 is 

returned. 

array First element of real array to be searched 

ine Skip distance between elements of the searched array 



target Real value searched for in array. If target is not 
found, then the returned value is rfrl. 
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ISRCHFGE is used when the real array element is greater than or equal to 
the real target. 

Call from FORTRAN: 



location* ISRCHFGE ( n 9 array , ino , target ) 



n Number of elements to be searched. If n^Q, then 0 is 

returned. 

array First element of real array to be searched 

ino Skip distance between elements of the searched array 

target Real value searched for in array. If target is not 
found, then the returned value is nfl. 

ISRCHILT is used when the integer array element is less than the integer 
target. 

Call from FORTRAN: 



loeation^ISRCHiLT (ntiarray, ino, itarget) 



n Number of elements to be searched. If ?t<0 r then 0 is 

returned, 

iarray First element of integer array to be searched 

ino Skip distance between elements of the searched array 

itarget Integer value searched for in array. If itarget is not 
found, then the returned value is nfl. 



ISRCHILE is used when the integer array element is less than or equal to 
the integer target. 

Call from FORTRAN: 



loeation=lSRCHILE(ni iarray tine, itarget) 



n Number of elements to be searched. If n<0, then 0 is 

returned. 
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iarray First element of integer array to be searched 

ine Skip distance between elements of the searched array 

itarget Integer value searched for in array. If itarget is not 
found, then the returned value is n+1. 



ISRCHIGT is used when the integer array element is greater than the 
integer target* 

Call from FORTRAN: 



loeation-ISRCHIGT (n r iarray ,inc, itarget ) 



n Number of elements to be searched* If n<0, then 0 is 

returned, 

iarray First element of integer array to be searched 

ine Skip distance between elements of the searched array 

itarget Integer value searched for in array. If itarget is not 
found, then the returned value is rr+1, 



ISRCHIGE is used when the integer array element is greater than or equal 
to the integer target. 

Call from FORTRAN: 



loeation-ISRCHIGE (n, iarray , ine, itarget) 



n Number of elements to be searched. If w<0, then 0 is 

returned, 

iarray First element of integer array to be searched 

ine Skip distance between elements of the searched array 

itarget Integer value searched for in array. If target is not 
found, then the returned value is n+1. 



INDEXED ARRAY OF ALL POSITIONS OF AN OBJECT IN A VECTOR 

These routines return all locations in an array that have a true 
relational value to the target. Table 4-7 summarizes these routines. 
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Table 4-7 ♦ WHEN routines 



Name (parameter list) 



Description 



WHENEQ (n , array ,ine, target , 
index, rival) 

WHENNE ( n , array ,ine, target , 
index, nval) 

WHENFLT { n , array ,ino, target , 
index, nval) 

whenfle ( n , array ,ine, target , 
index, nval) 



WHENFGT (n , array ,inc, targe t , 
index, nval) 

WHENFGE ( n , array t inc, target , 
index, nval) 



wheneq (n , iarray ,inc, itarget , 
index, nval) 



WHENNE (n , iarray 9 inc , itarget , 
index, nval) 



WHENILT {n, iarray 9 inc, itarget, 
index, nval) 



WHENILE (n, iarray , inc, itarget, 
index, nval) 



WHENIGT In , iarray , inc , itarget , 
index, nval) 



WHENIGE (n , iarray , ine, %target, 
index, nval) 



Returns all locations in a real array 
that are equal to the real target 

Returns all locations in a real array 
that are not equal to the real target 

Returns all locations in a real array 
that are less than the real target 

Returns all locations in a real array 
that are less than or equal to the real 
target 

Returns all locations in a real array 
that are greater than the real target 

Returns all locations in a real array 
that are greater than or equal to the 
real target 

Returns all locations in an integer 
array that are equal to the integer 
target 

Returns all locations in an integer 
array that are equal to the integer 
target 

Returns all locations in an integer 
array that are less than the integer 
target 

Returns all locations in an integer 
array that are less than or equal to the 
integer target 

Returns all locations in an integer 
array that are greater than the integer 
target 

Returns all locations in an integer 
array that are greater than or equal to 
the integer target 
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WHENEQ is used when the real array element is equal to the real target or 
the integer array is equal to the integer target. 

Call from FORTRAN: 

CALL WHENEQ (n, array tine, target, index ,nval) 
CALL WHENEQ (n, iarray, ine, itarget, index, nval) 



n 


Number of elements to be searched 


array 


First element of real array to be searched 


iarray 


First element of integer array to be searched 


ine 


Skip distance between elements of the searched array 


target 


Real value searched for in array 


itarget 


Integer value searched for in array 


index 


Integer array containing the index of the found target in 




the array 


nval 


Number of values put in the index array 



The FORTRAN equivalent follows. 

INA=1 
NVAL-0 

IF(INC.LT.O) INA«(-INC)*(N-1)+1 
DO 100 I-1,N 

IF (ARRAY ( INA) . EQ . TARGET) THEN 
NVAL=NVAL+1 

INDEX (NVAL) =1 
END IF 

INA=INA+INC 

100 CONTINUE 

WHENNE is used when the real array element is not equal to the real 
target or the integer array is not equal to the integer target. 
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Call from FORTRAN: 



call WHENNE (n , array 9 ine 9 target , index ,nval ) 
CALL WHENNE (n , iarray, ine, itarget, index, nval) 



n Number of elements to be searched 

array First element of real array to be searched 

iarray First element of integer array to be searched 

ine Skip distance between elements of the searched array 

target Real value searched for in array 

itarget Integer value searched for in array 

index Integer array containing the index of the found target in 
the array 

nval Number of values put in the index array 

WHENFLT is used when the real array element is less than the real target. 
Call from FORTRAN: 



CALL WHENFLT (n , array 9 ine # target , index 9 nval ) 



n Number of elements to be searched 

array First element of real array to be searched 

ine Skip distance between elements of the searched array 

target Real value searched for in array 

index Integer array containing the index of the found target in 
the array 

nval Number of values put in the index array 



WHENFLE is used when the real array element is less than or equal to the 
real target. 
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Call from FORTRAN: 



CALL WHENFLE (n t array ,inc, target , index ,nval) 



n Number of elements to be searched 

array First element of real array to be searched 

inc Skip distance between elements of the searched array 

target Real value searched for in array 

index Integer array containing the index of the found target in 
the array 

nvdl Number of values put in the index array 



WHENFGT is used when the real array element is greater than the real 
target. 

Call from FORTRAN: 



CALL WHENFGT (n , array ,inc, target , index ,nval) 



n Number of elements to be searched 

array First element of real array to be searched 

inc Skip distance between elements of the searched array 

target Real value searched for in array 

index integer array containing the index of the found target in 
the array 

nvdl Number of values put in the index array 



WHENFGE is used when the real array element is greater than or equal to 
the real target. 

Call from FORTRAN: 



CALL WHENFGE (n, array ,ine, tar get , index, nval) 
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n Number of elements to be searched 

array First element of real array to be searched 

ine Skip distance between elements of the searched array 

target Real value searched for in array 

index Integer array containing the index of the found target in 
the array 

rival Number of values put in the index array 



WHENILT is used when the integer array element is less than the integer 
target. 

Call from FORTRAN: 

CALL WHENILT (n , iarray, ine, itarget , index, nval) 



n Number of elements to be searched 

iarray First element of integer array to be searched 

ine Skip distance between elements of the searched array 

itarget Integer value searched for in array 

index Integer array containing the index of the found target in 
the array 

nval Number of values put in the index array 



WHENILE is used when the integer array element is less than or equal to 
the integer target* 

Call from FORTRAN: 

CALL WHENILE (n , iarray ,ine, itarget , index, nval) 

n Number of elements to be searched 

iarray First element of integer array to be searched 

ino Skip distance between elements of the searched array 
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itarget Integer value searched for in array 

index Integer array containing the index of the found target in 
the array 

rival Number of values put in the index array 



WHENIGT is used when the integer array element is greater than the 
integer target • 

Call from FORTRAN: 



CALL whenigt (n , iarray , inc , itarget , index, nval) 



n Number of elements to be searched 

iarray First element of integer array to be searched 

ine Skip distance between elements of the searched array 

itarget Integer value searched for in array 

index Integer array containing the index of the found target in 
the array 

nval Number of values put in the index array 



WHENIGE is used when the integer array element is greater than or equal 
to the integer target, 

Call from FORTRAN: 



CALL WHENIGE (n, iarray, inc, itarget, index, nval) 



n Number of elements to be searched 

iarray First element of integer array to be searched 

ine Skip distance between elements of the searched array 

itarget Integer value searched for in array 
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index 



Integer array containing the index of the found target in 
the array 



rival 



Number of values put in the index array 



SEARCH ORDERED ARRAY FOR TARGET 

These subroutines search integer arrays for integer targets and search 
real arrays for real targets* 



OSRCHI searches an ordered integer array and returns the index of the 
first location that contains the target (type integer) . Searching always 
begins at the lowest value in the ordered array. Even if the target is 
not found, OSRCHI returns the index of the location that would contain 
the target. The total number of occurrences of the target in the array 
can also be returned. 

Call from FORTRAN: 



CALL OSRCHI {n, iarr i ay ,inc,itar get , index 9 iwhere 9 inum) 



n Number of elements of the array to be searched 

iaway Beginning address of the integer array to be searched 

ine A positive skip increment indicates an ascending array and 



returns the index of the first element encountered r 
starting at the beginning of the array. 

A negative skip increment indicates a descending array and 
returns the index of the last element encountered, starting 
at the beginning of the array. 



itarget 



Integer target of the search 



index 



Index of the first location in the searched array that 
contains the target 



Exceptional cases: 

(1) if n < It index=0 

(2) If no equal array elements, index=n+l 
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where 



Index of the first location in the searched array that 
would contain the target if it were found in the array. 
(If the target is found, index^iwhere.) 



Exceptional case: if n is less than 1, iwhere=Q 



irtwn 



Number of target elements found in the array. For the 
total number of occurrences of the target in the array r 
this parameter must be specified nonzero. 



OSRCHF searches an ordered real array and returns the index of the first 
location that contains the target (type real). Searching always begins 
at the lowest value in the ordered array. Even if the target is not 
found, OSRCHI returns the index of the location that would contain the 
target. As an option, the total number of occurrences of the target in 
the array can also be returned. 

Call from FORTRAN: 



CALL OSRCHF (n, array ,inc, target , index ,iwhere 9 inwn) 



n Number of elements of the array to be searched 

array Beginning address of the real array to be searched 

ine A positive skip increment indicates an ascending array and 



returns the index of the first element encountered, 
starting at the beginning of the array. 

A negative skip increment indicates a descending array and 
returns the index of the last element encountered, starting 
at the beginning of the array. 



target 



Real target of the search 



index 



Index of the first location in the searched array that 
contains the target 



Exceptional cases: 

(1) If n < 1, indeo^O 

(2) If no equal array elements, index=?Hl 



iwhere 



Index of the first location in the searched array that 
would contain the target if it were found in the array. 
(If the target is found, index=iwhere*) 



Exceptional case: if n is less than 1, iwhere^O 
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inum 



Number of target elements found in the array. For the 
total number of occurrences of the target in the array, 
this parameter must be specified nonzero. 



SORT ROUTINE 

ORDERS is an internal fixed-length record sort optimized for the Cray 
computer. It assumes that the n records to be sorted are of length 
ireclth and have been stored in an array data that has been 
dimensioned. The ORDERS method and processing are described later. 



DIMENSION DATh(iveelth t n) 



ORDERS does not move records within data but returns a vector index 
containing pointers to each of the records in ascending order. For 
example, DATA (1, INDEX (1) ) is the first word of the record with smallest 
key. 

Call from FORTRAN: 



CALL ORDERS {mode , iwork , data, index, n , ireclth, ikey Ith, iradeiz) 



Although the number of arguments and their interconnections are 
complicated, careful use can save significant execution time. 

mode Integer flag; describes the type of key and indicates an 

initial ordering of the records. 

Upon completion of a call, ORDERS returns an error flag in 
mode. A value equal to the input mode value indicates 
no errors. A value less than 0 indicates an error. 

-1 Too few arguments; must be greater than 4. 

-2 Too many arguments; must be less than 9. 

-3 Number of words per record less than 1 or greater than 
2**24 

-4 Length of key greater than the record 
-5 Radix not equal to 1 or 2 
-6 Key less than one byte long 
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»7 Number of records less than 1 or greater than 2**24 

-8 Invalid mode input values: must be 0, 1, 2, 10, 11 , 
or 12. 

-9 Key length must be eight bytes for real or integer sort, 

0 The key is binary numbers of length &*ikeylth+ 
These numbers are considered positive integers in 
the range of 0 to 2 ( 8 *^eUftJ (The ordering 

of ASCII characters is the same as their ordering as 
positive integers*) 

1 The key is 64-bit Cray integers. These are twos 
complement signed integers in the range of -2« to 
+2 63 . (The key length, if specified, must be 
eight bytes.) 

2 The key is 64-bit Cray floating-point numbers. (The 
key length, if specified, must be eight bytes.) 

10 The key is the same as mode-Q, but the array INDEX 
has an initial ordering of the records (see 
multipass sorting, later in this section) . 

11 The key is the same as mode=l, but the array INDEX 
has an initial ordering of the records. 

12 The key is the same as mode=2, but the array INDEX 
has an initial ordering of the records. 

iwovk User-supplied working storage array of length K where K=257 
if iradsi^l, or K-65537 if iradsiz^2 

data Array dimensioned ireelth by N containing the N records 

of length ireelth each* The key in each record starts at 
the left of the first word of the record and continues 
ikeylth bytes into successive words as necessary. (By 
offsetting this address, any word within the record can be 
used as a key. See sort examples at the end of this 
section* ) 

index Integer array of length N containing pointers to the 
records. In mode=10, 11, or 12, index contains an 
initial ordering of the records (see multipass sorting, 
later in this section). On output, index contains the 
ordering of the records? that is, DATA(1,INDEX(I) ) is the 
first word of the record with smallest key and 
DATA (1, INDEX (N) ) is the first word of the record with the 
largest key. 

n Number of records to be sorted. Must be >1 
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ireolth 



ikeylth 
iradsiz 



Length of each record as a number of 64-bit words . Default 
is 1. ireclth is used as a skip for vector loads and 
stores • Therefore, ireclth should be chosen to avoid 
bank conflicts. 



Length of each key as a number of 8-bit bytes, 
eight bytes (1 word) . 



Default is 



Radix of the sort, iradsiz is the number of bytes 
processed per pass over the records . Default is 1, 
section on large radix sorting for iradaiz^Z* 



See 



METHOD 

ORDERS uses the radix sort, more commonly known as a bucket or pocket 
sort. For this sort, the length of the key in bytes determines the 
number of passes made through all of the records. The method has a 
linear work factor and is stable in that the original order of records 
with equal keys is preserved. 

ORDERS has the option of processing one or two bytes of the key per pass 
through the records. This process halves the number of passes through 
the record but at the expense of increased working storage and overhead 
per pass (see table 4-8) . ORDERS can sort on several keys within a 
record by using its multipass capability. The first eight bytes of the 
keys use a radix sort. If the key length is greater than eight bytes and 
any records have the first eight bytes equal, these records are sorted 
using a simple bubble sort. Using the bubble sort with many records is 
time-consuming. Therefore, the multipass option should be used instead. 

ORDERS has been optimized in CAL to make efficient use of the vector 
registers and functional units at each step of a pass through the data. 
Keys are read into vector registers with a skip through memory of 
ireclth* Therefore, ireclth should be chosen to avoid bank conflicts. 



Large radix sorting 

The number of times the key of each record is read from memory is 
proportional to ikeylth/iradsiz* Using ORDERS with iradsiz-2 
halves this ratio because two bytes instead of one are processed each 
time the key is read. One disadvantage of halving the number of passes 
is the user-supplied working storage array goes from 257 words to 65537 
words. Also, a 2-byte pass requires that each pass now use a greater 
overhead for setup. These two factors favor a 1-byte pass for sorting up 
to about 5000 records. For more than 5000 records, however, a 2-byte 
pass is faster. 
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Multipass sorting 



Because the array INDEX can define an ordering of the records , several 
calls can be made to ORDERS where the order of the records is that of the 
previous call. mode^lO, 11, or 12 specifies that the array INDEX 
contains an ordering from a previous call to ORDERS. This specification 
allows sorting of text keys that extend over more than one word or keys 
involving double-precision numbers. (See examples at the end of this 
section.) Although the length of the key is limited only by the length 
of the record, up to eight bytes are sorted with the radix sort. The 
remaining key is sorted using a bubble sort, but only in those records 
whose keys are equal for the first eight bytes. Therefore, a uniformly 
distributed key over the first eight bytes of length greater than eight 
bytes might be sorted faster with a single call with a large IKEYLTH 
rather than with a multipass call (see table 4-9) . Note also that when 
using the multipass capability, the least significant word must be sorted 
first. 

Tables 4-8 and 4-9 show the processing of one or two bytes of a key per 
pass through the records for a 16-bank CRAY 1-S Computer System. 



Table 4-8. Sort times in seconds for ORDERS 



Length of key in bytes 




N 


7 


8 


15 




2 


.00057 


.00065 


.00065 




5 


.00059 


.00067 


.00067 


One 


10 


.00060 


.00069 


.00070 


byte 


50 


.00080 


.00092 


.00095 


per 


100 


.00105 


.00120 


.00125 


pass 


500 


.00299 


.00342 


.00370 




1,000 


.00543 


.00616 


.00678 




5,000 


.02480 


.02824 


.03118 




10,000 


.04906 


.05585 


.06173 




2 


.01515 


.01520 


.01513 




5 


.01510 


.01511 


.01519 


Two 


10 


.01507 


.01511 


.01512 


bytes 


50 


.01522 


.01522 


.01525 


per 


100 


.01540 


.01542 


.01547 


pass 


500 


.01651 


.01642 


.01679 




1,000 


.01781 


.01786 


.01838 




5,000 


.02486 


.02861 


.03156 




10,000 


.04216 


.04216 


.04808 
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Table 4-9. Sort times in seconds with ASCII key 



N 


Two passes 


One pass 




8-byte Key 


16-byte Key 


2 


.00131 


. 00065 

• v V Vr V 


5 


.00135 


.00068 


10 


.00140 


.00072 


50 


.00191 


.00104 


100 


.00258 


.00145 


500 


.00796 


.00485 


1,000 


.01470 


.00907 


5, 000 


.06874 


.04307 


10,000 


.13602 


.08531 



Example 1: 

PROGRAM SORT1 

C 

C Sort on a 2-word (16-byte) key that is at the beginning of 

C a 5-word (inclusive) record 

C 

DIMENSION DATA(5,N) 
DIMENSION INDEX (N) 
DIMENSION WORK (65537) 
N=10000 

C 

MODE=0 

C 

CALL ORDERS (MODE , WORK , DATA , INDEX ,N,5,16,2) 

C 

C Print out the keys in increasing alphabetic order 
C 

DO 100 1=1, N 

WRITE(6 f 200) DATA(1, INDEX (I)), DATA ( 2 , INDEX (I)) 
200 FORMAT (IX, 2 A8) 
100 CONTINUE 

C 

END 



Example 2: 

PROGRAM SORT2 

C 
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C This program uses two calls to ORDERS to completely sort an array 

C of double-precision numbers. The sign bit of the first 

C word is used to change the second word into a text key that 

C preserves the order ing. A sort is done on these six bytes of the 

C second word. (The changes made to the second word are reversed 

C after the call.) Last, a sort is done on the first word as a 

C real key using the initial ordering from the previous call. 

C 

DOUBLE PRECISION DATA(IOO) 
INTEGER IATA(200) 
EQUIVALENCE ( I AT A, DATA) 
INTEGER INDEX(IOO), WORK(257) 
N=12 

DO 5 1*1, N 

DATA(I) = (-1, DO)**10.DO*M-20)*DBLE(RANF() ) 
5 CONTINUE 

C 

C First the second word key is changed 
C 

DO 10 I~2, 2*N, 2 

IF(DATA(I/2) .LE.0.DO) THEN 

I ATA { I ) =COMPL ( I ATA ( I ) ) 
ELSE 

IATA(I)=IATA(I) 
ENDIF 
10 CONTINUE 

C 

C Sort on second word 
C 

CALL ORDERS (0, WORK, IATA( 2) , INDEX, N, 2, 6, 1) 

C 

C Restore second word to original form 
C 

DO 20 1=2, 2*N, 2 

IF(DATA(I/2) .LE.O.DO) THEN 

I ATA ( I ) «CGMPL ( I ATA (I) ) 
ELSE 

IATA(I)=IATA{I) 
ENDIF 
20 CONTINUE 

C 

C Sort on the first word using the initial ordering 
C 

CALL ORDERS (12, SORT , DATA , INDEX , N , 2 , 8 , 1 ) 
DO 50 1=1, N 

WRITE(6, 900)1, INDEX(I), DATA (INDEX (I) ) 
50 CONTINUE 

900 FORMAT (lx, 215, 2x, D40.30) 
END 
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INPUT/OUTPUT SUBPROGRAMS 



INTRODUCTION 

The following types of subprograms perform input or output operations on 
COS datasets, 

m FORTRAN I/O routines 

• Tape translation routines 

• Explicit data conversion routines 

• Dataset control routines 

• Logical record I/O routines 

• Numeric conversion routines 

• Random access dataset I/O routines 

• Word-addressable I/O routines 



FORTRAN I/O ROUTINES 

The FORTRAN I/O routines described in this section provide the highest 
level of user interface with COS datasets. They include formatted and 
unformatted routines, call-by-address and call-by-value routines, vector 
and scalar routines, namelist routines, and buffered input and output 
routines. 



NOTE 

All formatted I/O is restricted to an input/output list 
and format specification of not more than 152 
characters . To change this default, COMDECK $COMMB in 

$IOLIB can be modified and an alternate library built. 



SR-0014 



5-1 



I 



These routines fall into one of the following categories, 

• Initialization 

• Data transfer 

• Finalization 

The routines are named and their functions summarized in table 5-1. 



Table 5-1. FORTRAN I/O routines 



Operation 
Sequence 


Read 
Form, 


Write 
Form. 


Read 
Unf. 


Write 
Unf. 


Decode 


Encode 


Read 
L-d. 


Write 
L-d. 


Initialization 
routines 


$RFI 


$WFI 


$RUI 


$WUI 


$DFI 


$EFI 


$RLI 


$WLI 


Transfer 
routines 
call-by-address 


$RFA 


$WFA 


$RUA 


$WUA 


$DFA 


$EFA 


$RLA 


$WLA 


Transfer 
routines 
call-by-value 


$RFV 


$WFV 


$RUV 


$WUV 


$DFV 


$EFV 






Termination 
routines 


$RFF 


$WFF 


$RUF 


$WUF 


$DFF 


$EFF 


$RLF 


$WLF 



Each FORTRAN read/write statement not associated with namelist processing 
generates a call to an I/O initialization routine and a call to an I/O 
finalization routine. Between these two calls, I/O list items are 
processed using transfer routines. These transfer routines are 
classified as either call-by-value or call-by-address. Each list item 
generates a corresponding c^ll to one of the two types of routines. 

Transfer-by-value is selected for simple variables, constants, 
expressions, or implied DO lists. Transfer-by-value transfers a single 
value or a vector of values. Transfer-by-address is selected for an 
array name as a list item. 
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INITIALIZATION ROUTINES 



Initialization routines process control information lists and set up 
parameters for the processing of the corresponding transfer routines. 
These routines, identified by the I suffix, are executed before the 
transfer routines. No arguments are returned. No initialization is 
required for namelist I/O or buffered I/O. All initialization routines 
are called by address. 



Input initialization routines 

$RFI initializes FORTRAN formatted read. 

Call from CAL: 



CALL $RFI, (arg 1 ,arg 2 l,arg 3 ] [,arg A ] [,arg 5 ] l,arg 6 ]) 



Address of unit name or number, or internal file 

Address of FORMAT specification 

Address of error exit address, ERR= 

Address of end exit address, END= 

Address of IOSTAT parameter 

Address of record number (direct access) 



$RUI initializes FORTRAN unformatted read. 
Call from CAL: 



CALL $RUI, (arg ± [ r f arg 3 ] [,ar^ 4 ] l,arg 5 ] [,arg 6 ]) 



Address of unit name or number 
Unused 

Address of error exit address, ERR= 
Address of end exit address, END= 
Address of IOSTAT parameter 
Address of record number (direct access) 



$DFI initializes FORTRAN formatted decode. 
Call from CAL: 



CALL $DFI , (apg± 9 arg 2 r ) 



arg x 
arg 2 
avg 3 

arg 5 
a *9e 



a?g x 
avg 2 
arg 3 

arg 5 
ar>g 6 
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avg 1 

arg 2 
arg 3 



Address of record length in Cray characters 
Address of FORMAT specification 
Address of input character string 



$RLI initializes list-directed reads* 
Call from CAL: 



CALL $RLI, (arg^, r arg 3 ] [,arg 4 ) l,arg 5 }) 



Address of unit name or number 
Unused 

Address of error exit for ERR= 
Address of exit address for END- 
Address of IOSTAT parameter 



Output initialization routines 

$WFI initializes FORTRAN formatted write* 

Call from CAL: 



CALL $WFI, (arg lf arg 2 [ f arg 3 ) l,,ai>g 5 ] l,arg 6 ] 



Address of unit name or number , or internal file 
Address of FORMAT specification 
Address of error exit address 
Unused 

Address of IOSTAT parameter 

Address of record number {direct access) 



$WUI initializes FORTRAN unformatted write. 
Call from CAL: 



CALL $WJI,(arg 1 [,,arg 3 ] [ f ,arg 5 ] [,arg 6 ]) 



Address of unit name or number 
Unused 

Address of error exit address 
Unused 

Address of IOSTAT parameter 

Address of record number (direct access) 



ax*g x 
avg 2 
arg 3 

arg 5 



arg ± 
arg 2 
arg 3 
arg A 
arg 5 



avg x 

arg 2 
avg 3 
arg 4 
arg 5 

a *$6 
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$EFI initializes FORTRAN formatted encode. 
Call from CAL: 



CALL $EFI, Kapg-ytavg^fCLvg^) 



avg^ Address of record length in Cray characters 

arg 2 Address of FORMAT specification 

arg^ Address of output character string 

$WLI initializes list-directed writes. 
Call from CAL: 



CALL $WLI , (arg 1 [ , , arg^ \{ , , avg 5 I ) 



avg-y Address of unit name or number 

arg 2 Unused 

arg^ Address of error exit for ERR* 

avg± Unused 

avg$ Address of IOSTAT parameter 



TRANSFER ROUTINES 

Read and write transfer routines move data between user locations and the 
system I/O buffer area allocated to a dataset and associated with a 
particular I/O unit. Encode and decode transfer routines transfer data 
between user locations and a user-supplied buffer. The user-supplied 
buffer contains eight characters per word and has no I/O unit 
association. All dataset processing by these routines is sequential. 
Transfer routine names are identified by the suffix A for call-by-address 
routines and by the suffix V for call-by-value routines. 

Each formatted, unformatted, and buffered transfer routine has eight 
entry points. Each entry point corresponds to the type of data specified 
in the I/O list and is the name of the routine (xnom) plus an increment 
parcel value. Below is a list of the entry points showing the FORTRAN 
data type accommodated: 

Entry point Type of data 

xnam+0 Typeless (Boolean) or no I/O list or type 

checking present 
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Entry point 



Type of data 



xnam+3 



Integer 



xnam±6 



Real 



xnam*9 



Double-precision 



xnarm-12 



Complex 



xnam+15 



Logical 



xnarrn-is 



Character 



xnam21 



Short integer 



If an increment parcel value is omitted, typing is determined from the 
format specification edit descriptor. The increment value can be omitted 
for all data types except double-precision. For complex values, however, 
if the increment value is omitted (or if xnantf-6 is specified) , two calls 
must be made, one for the real portion and one for the imaginary 
portion. In these cases, the complex number is treated as two real 
numbers. 

Format specifications identified for initialization routines and used by 
transfer routines are described in the FORTRAN (CFT) Reference Manual, 
CRI publication SR^0009. 

Restrictions on the format specifications for integer, logical and real 
variables can be relaxed by using SEGLDR and its EQUIV options. See the 
FORTRAN (CFT) Reference Manual, CRI publication SR-0009 for details. 

Acknowledgement of the reading of an end-of-file (EOF) must occur before 
initiating another read operation on the same unit. Acknowledgement can 
be made by providing an EOF exit address, or by writing, rewinding, or 
backspacing the dataset. 

Buffered I/O is a form of data transfer allowing the execution of other 
statements to proceed simultaneously with the actual transfer. The 
number of words for one data transfer is represented by (lwa-fwa+l) . 
If the remaining words in the record are to be skipped, full record mode 
must be specified. Full record mode resumes transferring at the 
beginning of the next record. If the rest of the record is to be 
transferred, partial record mode must be specified. 



Formatted and unformatted input transfer routines 

The following transfer routines are called by address. 
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$RFA reads FORTRAN formatted data, 
$ROA reads FORTRAN unformatted data. 
$DFA decodes FORTRAN formatted data. 

Call from CAL: 



CALL $RFA+offset, (avg^avg^avg^) 
CALL $RUA+offset, (arg^, (&Q2' av Q$ 
CALL $DFA+offset, {a*»£ lf or^'^* 1 ^ 



arg^ First word address destination 

avg2 Address of word count 

arg^ Address of increment between destination addresses 



$RLA reads list-directed data by address. 
Call from CAL: 



CALL $RLA+offset, (org ^,arg 2 farg 3 ) 



First word address of input 
First word address of item count 
First word address of increment between items 

The following transfer routines are called by value. 

$RFV, $RFV% read FORTRAN formatted data. 
$RUV, $RUV% read FORTRAN unformatted data. 
$DFV, $DFV% decode FORTRAN formatted data. 

Call from CAL: 



CALLV $RFV+offset 
CALLV $RUV+of f set 
CALLV $DFV+offset 



Exit : 

(51) Requested value 

(52) Second value if transfer is for double-precision or complex 
values 



arg 2 
arg 3 
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%$RFV% reads FORTRAN formatted, vectorized data, 
%$RUV% reads FORTRAN unformatted, vectorized data* 

Call from CAL: 



CALLV 


%RFV%+offset 


CALLV 


%RUV%+offset 


Entry: 



(VL) Vector length 
Exit: 

(VI) (VL) requested values 

(V2) (VL) second values if transfer is for double-precision or 
complex values 

Buffered input transfer routines 

$RB performs FORTRAN read buffered operation. 

Call from CAL: 



CALL $RB+offset, (argi r arg 2 r^g2' ar 94^ 



Entry: 

arg± Address of unit name or number 

avQ2 Address of mode specifier (mode<0 indicates 

partial record transfer; mode>0 indicates full record 

transfer) . 

arg^ First word address of destination 
arg^ Last word address of destination 
Exit: 

Transfer from unit to first word of destination is initiated. 
Control is returned to the calling program. To test for completion 
of transfer, the user should issue a call to the routine UNIT or 
LENGTH. 



Namelist input transfer routines 
$RNL reads FORTRAN namelist. 
Call from CAL: 



CALL $RNL , (arg 1 , avg 2 I , ar>g 3 , J [ , arg 4 ] ) 
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avg 2 
arg 4 



Address of unit name or number 
Address of NAMELIST group entries 
Address of ERR*address 
Address of END*=address 



Namelist group entries for variables consist of a group name (one word) 
plus a 2-word entry. Namelist group entries for arrays consist of a 
group name (one word) plus (w+2) words, where n is the number of 
dimensions in the array. The first word of the list is always the group 
name. The order of the variable and array entries in the list is the 
same as specified on the NAMELIST statement by the user. Figure 5-1 
shows the group name, figure 5-2 shows the variable entry f and figure 5-3 
shows the array entry. 



8 



16 



24 



32 



40 



48 



56 



63 



GN 



Figure 5-1. Group name 



Field 



GN 



Bits 
0-63 



Description 

8-bit ASCII name, left- justified, zero-filled 





0 8 16 


24 32 40 


48 56 


63 


0 


NAME /VAM EMM^ 


1 


//////////IM 


TL \//t\X///\ ) 


VA 






Figure 5-2. 


Variable entry 







Field 
NAME 

Unused 
M 

Unused 
TL 



Word 



1 

1 

1 
1 



Bits Description 

0-63 8-bit ASCII character name, 

left-justified, zero-filled 

0-10 Zero-filled 

11-13 Mode. Number of dimensions in the 

array (1-7) 

14-19 Zero-filled 

20-31 Internal CPT type and length 

description: 
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Field Wbrd Bits Description 



TL 


Description 


1077 


Logical 


4027 


24-bit integer 


4077 


64-bit integer 


6077 


Real 


6177 


Complex 


7177 


Double-precision 



Unused 1 32-33 Zero-filled 



VAM 1 34 

EMM 1 35 

Unused 1 36-39 

VA 1 40-63 



=0 if variable address is actual 
address 

=1 if variable address is stack 
offset from B03 

Value is 1 if variable address is 
24 bits 

Zero-filled 
Variable address 



16 



24 



32 



40 



48 



56 



63 



0 
1 

2-n 



Field 
NAME 

Unused 

M 

Unused 
TL 



NAME {VAM EMM\ 


////////// IM 


tl \//\\\ym) 


VA 


LB 




DL 



Word 



1 
1 

1 

1 



Figure 5-3. Array entry 
Description 



Bits 
0-63 

0-10 
11-13 

14-19 
20-31 



8-bit ASCII character name, 
left-justif ied, zero-filled 

Zero-filled 

Mode. Number of dimensions in the 
array (1-7) 

Zero-filled 

Internal CFT type and length 
description: 
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Field 



Word 



Bits 



Description 



TL 


Description 


1077 


Logical 


4027 


24-bit integer 


4077 


64-bit integer 


6077 


Real 


6177 


Complex 


7177 


Double-precision 



Unused 
VAM 



EMM 



Unused 
FWA 
LB 
DL 



1 
1 



1 
1 

2-n 
2-n 



32- 33 Zero-filled 

34 =0 if first word address of array is 
actual address 

=1 if first word address of array is 
stack offset from B03 

35 -0 if first word address of array is 
22 bits long. Top 2 bits are assumed 
zero. 

=1 if first word address of array is 
24 bits long 

35-39 Zero-filled 

40-63 First word address of array 

1-31 Lower bound of array dimension 

33- 63 Dimension length 



Formatted and unformatted output transfer routines 

The following transfer routines are called by address, 

$WFA writes FORTRAN formatted data. 
$WUA writes FORTRAN unformatted data. 
$EFA encodes FORTRAN formatted data. 



Call from CAL: 



CALL $WFA+offset # (arg lr ar^ 2 r^g r 3) 
CALL $WUA+offset, (arg^ f arg2rdrg^) 
CALL $EFA+offset, {arg^,arg2rdrg2) 



arg^ First word address destination 

ax*g2 Address of word count 

avg^ Address of increment between destination addresses 
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$WLA writes list-directed data by address • 
Call from CAL: 



CALL $WLA+cffset, (ar^ lf ar^ 2 #^^3) 



arg 3 



First word address of input 

First word address of item count 

First word address of increment between items 



The following transfer routines are called by value, 

$WFV, $WFV% write FORTRAN formatted data. 
$WUV, $WUV% write FORTRAN unformatted data. 
$EFV f $EFV% encode FORTRAN formatted data. 

Call from CAL: 



CALLV $WFV+offset 
CALLV $WUV+of f set 
CALLV $EFV+offset 



(51) Word to be written or encoded 

(52) Second word if double-precision or complex values 



%$WFV% writes FORTRAN format ted , vectorized data. 
%$WUV% writes FORTRAN unformatted, vectorized data. 

Call from CAL; 



r 



CALLV %$WFV%+offset 
CALLV %$WUV%+offset 



(VL) 
(VI) 
(V2) 



Vector length 
(VL) requested values 

Second values if transfer is for double-precision or 
complex values 
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$WLV writes list-directed data by value. 
Call from CAL: 



CALLV $WLV+offset 



(51) Word to be written 

(52) Second word if double-precision or complex 



Buffered output transfer routines 

$WB performs FORTRAN write buffered operation. 

Call from CAL: 



CALL $WB+of fset, (arg^ 9 arg29arg^ 9 arg^) 



Entry: 

arg± Address of unit name or number 

arg2 Address of mode specifier (mode<0 indicates partial 

record transfer; mode>0 indicates full record transfer). 

org 2 First word address of destination 
Last word address of destination 

Exit: 

Transfer from unit to first word of destination is initiated. 
Control is returned to the calling program. To test for completion 
of transfer , issue a call to the routine UNIT or LENGTH. 



Namelist output transfer routines 
$WNL writes FORTRAN namelist. 
Call from CAL: 



CALL $WNL, (arg lt arg 2 I 9 arg^} ) 



argi Address of unit name or number 

arg 2 Address of NAMELIST group entries 

org 3 Address of ERR=address 
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FINALIZATION ROUTINES 



Finalization routines, suffixed by F, terminate a record and clear the 
control information list parameters set up by the corresponding 
initialization routines. No arguments are required for entry; no 
arguments are returned. All linkage is call-by-address. Finalization 
routines are unnecessary for namelist I/O and buffered I/O. 

Input finalization routines 

$RFF finalizes FORTRAN formatted read. 

Call from CAL: 

CALL $RFF 



$RUF finalizes FORTRAN unformatted read. 
Call from CAL; 

CALL $RUF 



$DFF finalizes FORTRAN formatted decode. 
Call from CAL: 

CALL $DFF 



$RLF finalizes list-directed read. 
Call from CAL: 

CALL $RLF 



Output finalization routines 

$WFF finalizes FORTRAN formatted write. 
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Call from CAL: 



CALL $WFF 



$WUF finalizes FORTRAN unformatted write. 
Call from CAL: 

CALL $WUF 



$WLF finalizes list-directed write. 
Call from CAL: 

CALL $WLF 



$EFF finalizes FORTRAN formatted encode. 
Call from CAL: 

CALL $EFF 



TAPE TRANSLATION ROUTINES 

The tape translation routines provide for reading and writing tapes that 
have been written or are going to be read on computers with different 
character sets or data formats from those of the Cray computer. Through 
the ACCESS or ASSIGN control statement (refer to the CRAY-OS Version 1 
Reference Manual, publication SR-0011) FORTRAN users can provide foreign 
tape file characteristics. These parameters are used by the run-time 
library to correctly translate the dataset. Support is supplied through 
FORTRAN'S formatted, unformatted, and buffered I/O. 

A formatted or unformatted transfer routine is called once for each 
variable in the I/O list. (See transfer routines, this section.) The 
transfer routine then calls a buffer management routine. The buffer 
management routine makes a system request for physical I/O when 
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appropriate and processes the COS block and record control words (RCW) if 
the dataset is in COS blocked format. 

Buffer management routines call the record format management routines one 
or more times for each variable. Record format management routines keep 
track of the current logical record within the I/O buffer and determine 
the location of the requested variable within the logical record* They 
process a partial record and return a status indicating whether the end 
of the logical record has been reached. The record format management 
routines call the data format routines once for each element of the 
requested variable. The data format routines translate between the 
internal COS representation of the variable and the representation of the 
variable in the logical record. 



NOTE 

Some tape translation routines are included in all load 
modules performing I/O since the code must be included 
at load time but the dataset characteristics are not 
known until run time. 

If a user or site does not use foreign data types, 
comdeck $COMFD in $IOLIB can be modified and an 
alternate library built. Either IBM, CDC, or both 
forms of conversions can be disabled; the corresponding 
code is never loaded. Use of a disabled format is not 
detected; no conversion takes place. 



BUFFER MANAGEMENT ROUTINES 

The buffer management routines fill and empty the tape buffer, maintain 
information in the Dataset Parameter Table (DSP) to be saved between READ 
or WRITE statements, and determine which record translation routine is to 
be called. 

Input buffer management routines 
RUTI initializes buffer management. 
Call from GAL: 

CALL RUTI, (arg Y ) 
arg-^ DSP address 
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RUTD% reads data. 
Call from CAL: 



CALLV RUTD% 



(SI) 
(S2) 
(S3) 
(S4) 
(S5) 



First word address of data 
Number of data items 
Increment between data items 

Data type as defined by common deck $COMDT in $IOLIB 
Length of item in bytes (type character only) 



RUTF finalizes buffer management • 
Call from CAL: 

CALL RUTF 



Output buffer management routines 
WUTI initializes buffer management. 
Call from CAL; 

CALL WUTI, (arg) 

arg DSP address 

WDTD% writes data. 
Call from CAL: 

CALLV WUTD% 

(51) First word address of data 

(52) Number of data items 

(53) Increment between data items 

(54) Data type as defined by common deck $COMDT in $IOLIB 

(55) Length of item in bytes (type character only) 
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WUTF finalizes buffer management. 
Call from CAL: 

CALL WUTF 



RECORD FORMAT MANAGEMENT ROUTINES 

Record format management routines keep track of the particular vendor's 
record and block formats. These routines move the translated bits to or 
from the tape buffer and format them according to the record and block 
definitions. These routines are called by address. 

Input record format management routines 

$IBMI reads IBM file format. 
$CDCI reads CDC file format. 

Output record format management routines 

$IBMO writes IBM file format. 
$CDCO writes CDC file format. 

DATA FORMAT MANAGEMENT ROUTINES 

Data format management routines translate the internal format of the 
particular variable type. They are accessed by call-by-value subprogram 
linkage. 

The naming convention for data format management routine is $STD. 
S System; codes are I (IBM), C (CDC). 

T Variable type and size; for example, 116 is a 16-bit integer. 
D Processing direction is I (input) or 0 (output) . 

Input data format management routines 

%II16l translates 16-bit IBM integer to 24-bit Cray integer on input. 
%II32I translates 32-bit IBM integer to 64-bit Cray integer on input. 
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%IL8I translates 8-bit IBM logical to 64-bit Cray logical on input ♦ 

%IF32I translates 32-bit IBM floating-point to 64-bit Cray floating-point 
on input. 

%ID64I translates 64-bit IBM double-precision floating-point to 128-bit 
Cray double-precision floating-point on input, 

%ICHRI translates 8-bit IBM EBCDIC character to 8-bit ASCII character on 
input. 

%IC64I translates 64-bit IBM complex floating-point to 128-bit Cray 
complex floating-point on input. 

CI60I% translates CDC 60-bit integer to 64-bit Cray integer on input, 

CF60I% translates CDC 60-bit floating-point to 64-bit Cray floating-point 
on input* 

CD120I% translates CDC 120-bit double-precision to 128-bit Cray 
double-precision floating-point on input. 

CC120I% translates CDC 120-bit complex number to 128-bit Cray complex 
floating-point on input. 

CCHRI% translates CDC 6-bit display code to 8-bit ASCII character on input. 
CL60I% translates CDC 60-bit logical to 64-bit Cray logical on input. 

Output data management format routines 

%II160 translates 16-bit IBM integer to 24-bit Cray integer on output. 

%II320 translates 32-bit IBM integer to 64-bit Cray integer on output. 

%IL80 translates 8-bit IBM logical to 64-bit Cray logical on output. 

%IF320 translates 32-bit IBM floating-point to 64-bit Cray floating-point 
on output. 

%ID640 translates 64-bit IBM double-precision floating-point to 128-bit 
Cray double-precision floating-point on output. 

%ICHRO translates 8-bit IBM EBCDIC character to 8-bit ASCII character on 
output. 
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%IC640 translates 64-bit IBM complex floating-point to 128-bit Cray 
complex floating-point on output, 

CI 600% translates 64-bit Cray integer to CDC 60-bit integer on output . 

CF60O% translates 64-bit Cray floating-point to CDC 60-bit floating-point 
on output. 

CD120O% translates 128-bit Cray double-precision floating-point to CDC 
120-bit double-precision on output. 

CC120O% translates 128-bit Cray complex floating-point to CDC 120-bit 
complex number on output. 

CCHBO% translates 8-bit ASCII character to CDC 6-bit display code on 
output ♦ 

CL60O* translates 64-bit Cray logical to CDC 60-bit logical on output. 



EXPLICIT DATA CONVERSION 

The explicit data conversion routines described in this subsection are 
subprograms that allow data translation between Cray internal 
representations and other vendors 1 data types. 



IBM SINGLE-PRECISION TO CRAY SINGLE-PRECISION ROUTINE 

The USSCTC subroutine converts IBM 32-bit floating-point numbers into Cray 
64-bit single-precision numbers. 

Call from FORTRAN: 



CALL USSCTC (fpn,ieb,de8t,nurn[ t inc] ) 



fpn Variable or array of any type or length containing IBM 

32-bit floating point numbers to convert 

isb Byte number to begin the conversion. Type integer variable, 

expression, or constant. Bytes are numbered from 1, 
beginning at the leftmost byte position of fpn. 

dest Variable or array of type real to contain the converted 

values 
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num Number of IBM floating-point numbers to convert. Type 

integer variable, expression, or constant. 

ino Memory increment for storing the conversion results in 

dest. Optional parameter of type integer variable, 
expression, or constant. Default value is 1. 



IBM DOUBLE-PRECISION TO CRAY SINGLE-PRECISION ROUTINE 

The USDCTC subroutine converts IBM 64-bit floating-point numbers into Cray 
64-bit single-precision numbers. 

Call from FORTRAN: 



CALL USDCTC ldpn,isb,de8t,num[,ine]) 



dpn Variable or array of any type or length containing IBM 

64-bit floating-point numbers to convert 

isb Byte number within dpn to begin the conversion. Type 

integer variable, expression, or constant. Bytes are 
numbered from 1, beginning at the leftmost byte position of 
dpn. 

dest Variable or array of type real to contain the converted 

values 

num Number of IBM 64-bit floating-point numbers to convert. 

Type integer variable, expression, or constant. 

inc Memory increment for storing the conversion results in 

dest. Optional parameter of type integer variable, 
expression, or constant. Default value is 1. 



IBM INTEGER TO CRAY INTEGER ROUTINE 

The USICTC subroutine converts both IBM INTEGER* 2 and INTEGER* 4 numbers 
into Cray 64-bit integer numbers. 

Call from FORTRAN: 

CALL USICTC (in, isb, dest, num, ten [,ine] ) 
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in Variable or array of any type or length containing IBM 

INTEGER* 2 or INTEGER* 4 numbers to convert 

isb Byte number to begin the conversion. Type integer variable r 

expression/ or constant. Bytes are numbered from 1, 
beginning at the leftmost byte position of in. 

dest Variable or array of type integer to contain the converted 

values 

num Number of IBM numbers to convert. Type integer variable , 

expression, or constant. 

ten Size of the IBM numbers to convert. This value must be 2 or 

4. A value of 2 indicates input integers are integer *2 
(16-bit) . A value of 4 indicates input integers are 
integerM (32-bit). Type integer variable, expression/ or 
constant. 

inc Memory increment for storing the conversion results in 

dest. Optional parameter of type integer variable, 
expression, or constant. Default value is 1. 



EBCDIC TO ASCII ROUTINE 

The USCCTC subroutine converts IBM EBCDIC data into ASCII data. The same 
array can be specified for output as for input only if isb = 1 and npw = 8. 

Call from FORTRAN: 



CALL USCCTC (src , isb, dest, num$ npo) I , iuo] ) 



src Variable or array of any type or length containing IBM 

EBCDIC data to convert 

isb Byte number to begin the conversion. Type integer variable, 

expression, or constant. Bytes are numbered from 1, 
beginning at the leftmost byte position of src. 

dest Variable or array of any type or length to contain the ASCII 

data. 

num Number of IBM EBCDIC characters to convert. Type integer 

variable, expression, or constant. 
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nptt Number of characters per word generated in dest* The 

npw characters are left-justified and blank-filled in each 
word of dest. Type integer variable, expression, or 
constant. Value must be from 1 to 8. 

iuo A value of nonzero specifies lowercase characters (a-z) to 

be translated to uppercase (A-Z) . A value of 0 results in 
no case translation. Optional parameter of type integer 
variable, expression, or constant. Default is no case 
translation. 



IBM PACKED DECIMAL FIELD TO INTEGER ROUTINE 

The USPCTC subroutine converts a specified number of bytes of an IBM 
packed decimal field to a 64-bit integer field. The input field must be 
valid packed decimal number less than 16 bytes long, of which only the 
rightmost 15 digits are converted. 

Call from FORTRAN; 



CALL USPCTC (are, isb,num r ian) 



src Variable or array of any type or length containing a valid 

IBM packed decimal field 

isb Byte number to begin the conversion. Type integer variable 

expression, or constant. Bytes are numbered from 1, 
beginning at the leftmost byte position of src* 

num Number of bytes to convert. Type integer variable, 

expression, or constant. 

ian Returned integer result 



IBM LOGICAL TO CRAY LOGICAL ROUTINE 

The USLCTC subroutine converts both IBM L0GICAL*1 and L0GICAL*4 values 
into Cray 64-bit logical values. 

Call from FORTRAN: 

CALL USLCTC (sve ,isb 9 dest, num, len[,inc] ) 
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svo Variable or array of any type or length containing IBM 

LOGICAL*l or LOGICAL* 4 values to convert. 

isb Byte number to begin the conversion. Type integer variable/ 

expression, or constant. Bytes are numbered from 1, 
beginning at the leftmost byte position of are* 

dest Variable or array of type logical to contain the converted 

values 

nwn Number of IBM logical values to be converted. Type integer 

variable, expression, or constant. 

ten Size of the IBM logical values to convert. This value must 

be 1 or 4. A value of 1 indicates input logical values are 
L0GICAL*1 (8-bit) . A value of 4 indicates input logical 
values are L0GICAL*4 (32-bit). Type integer variable, 
expression, or constant. 

ino Memory increment for storing the conversion results in 

dest* Optional parameter of type integer variable, 
expression, or constant. Default value is 1. 



CRAY SINGLE-PRECISION TO IBM SINGLE-PRECISION ROUTINE 

The USSCTI subroutine converts Cray 64-bit single-precision floating-point 
numbers to IBM 32-bit single-precision floating-point numbers. Numbers 
that produce an underflow when converted to IBM format are converted to 32 
binary zeros. Numbers that produce an overflow when converted to IBM 
format are converted to the largest IBM floating-point representation with 
the sign bit set if negative. An error parameter returns nonzero to 
indicate that one or more numbers converted produced an overflow. No such 
indication is given for underflow. 

Call from FORTRAN : 



CALL USSCTI (fprc, dest, isb, nwn,ier[ ,ine] ) 



fpn Variable or array of any length and type real, containing 

Cray 64-bit, single-precision, floating-point numbers to 
convert 

dest Variable or array of type real to contain the converted 

values 
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iab Byte number at which to begin storing the converted 

results. Type integer variable r expression, or constant. 
Bytes are numbered from 1, beginning at the leftmost byte 
position of dest. 

num Number of Cray floating-point numbers to convert. Type 

integer variable, expression, or constant. 

iei* Overflow indicator of type integer. Value is 0 if all Cray 

values convert to IBM values without overflow. Value is 
nonzero if one or more Cray values overflowed in the 
conversion . 

ino Memory increment for fetching the number to be converted. 

Optional parameter of type integer variable, expression, or 
constant. Default value is 1* 



CRAY SINGLE-PRECISION TO IBM DOUBLE-PRECISION ROUTINE 

The USDCTI subroutine converts Cray 64-bit single-precision floating-point 
number to IBM 64-bit double-precision floating-point numbers. Precision 
is extended by introducing 8 more bits into the rightmost byte of the 
fraction from the Cray number being converted. Numbers that produce an 
underflow when converted to IBM format are converted to 64 binary zeros. 
Numbers that produce an overflow when converted to IBM format are 
converted to the largest IBM floating-point representation with the sign 
bit set, if negative. An error parameter returns nonzero to indicate that 
one or more numbers converted produced an overflow. No such indication is 
given for underflow. 

Call from FORTRAN: 



CALL USDCTI ( f pn , de st,i &b , num 9 iev[ t ino] ) 



fpn Variable or array of any length and of type real, containing 

Cray single-precision floating-point numbers to convert 

dest Variable or array of type real to contain the converted 

values 

isb Byte number at which to begin storage of the converted 

results. Type integer variable, expression, or constant. 
Bytes are numbered from 1, beginning at the leftmost byte 
position of dest. 

num Number of Cray floating-point numbers to convert. Type 

integer variable, expression, or constant. 
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ier Overflow indicator of type integer. Value is 0 if all Cray 

values are converted to IBM values without overflow. Value 
is nonzero if one or more Cray values overflowed in the 
conversion. 

ino Memory increment for fetching the number to be converted. 

Optional parameter of type integer variable, express ion , or 
constant. Default value is 1. 



CRAY INTEGER TO IBM INTEGER ROUTINE 

The USICTI subroutine converts Cray 64-bit integer numbers into either IBM 
INTEGER* 2 or INTEGER* 4 numbers. Numbers that produce an overflow when 
converted to IBM format are converted to the largest IBM integer 
representation with the sign bit set if negative. An error parameter 
returns nonzero to indicate that one or more numbers converted produced an 
overflow. 

Call from FORTRAN: 



CALL USICTI (in r dest r isb,num r ten, ier [, ino] ) 



in Variable or array of any length and type integer, containing 

Cray integer numbers to convert 

dest Variable or array of type integer to contain the converted 

values 

isb Byte number at which to begin storing the converted 

results. Type integer variable, expression, or constant. 
Bytes are numbered from 1, beginning at the leftmost byte 
position of dest. 

num Number of Cray integers to convert. Type integer variable, 

expression, or constant. 

ten Size of the IBM result numbers. This value must be 2 or 4, 

A value of 2 indicates output integers are INTEGER* 2 
(16-bit) . A value of 4 indicates output integers are 
INTEGER* 4 (32-bit) . Type integer variable, expression, or 
constant . 
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ier Overflow indicator of type integer. Value is 0 if all Cray 

values are converted to IBM values without overflow. Value 
is nonzero if one or more Cray values overflowed in the 
conversion. 

ine Memory increment for fetching the number to be converted. 

Optional parameter of type integer variable, expression, or 
constant. Default value is 1. 



ASCII TO EBCDIC ROUTINE 

The USCCTI subroutine converts ASCII data to IBM EBCDIC data. All 
unprintable characters are converted to blanks. The same array can be 
specified for output as for input only if isb = 1 and nptD = 8. 

Call from FORTRAN: 



CALL USCCTI {src 9 dest 9 isb,num, npa { , inc] ) 



bvc Variable or array of any type or length containing ASCII 

data, left justified, in Cray words to convert, 

dest Variable or array of any type or length to contain the IBM 

EBCDIC data 

isb Byte number at which to begin generating EBCDIC characrters 

in dest. Type integer variable, expression, or constant. 
Bytes are numbered from 1, beginning at the leftmost byte 
position of dest. 

num Number of ASCII characters to convert. Type integer 

variable, expression, or constant. 

npv) Number of characters per word selected from sre. Value 

must be from 1 to 8. Type integer variable, expression, or 
constant. 

ine A value of nonzero specifies lowercase characters (a-z) to 

be translated to uppercase (A-Z) . A value of 0 results in 
no case translation. Optional parameter of type integer 
variable, expression, or constant. Default is no case 
translation. 
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INTEGER TO IBM PACKED DECIMAL FIELD ROUTINE 

The USICTP subroutine converts a Cray 64-bit integer value to an 
IBM-packed decimal field. If the input value contains more digits than 
can be stored in num bytes, the leftmost digits are not converted. 

Call from FORTRAN: 



CALL VSiCTP{ian, dest, isb, num) 



ian Cray integer number to be converted to an IBM-packed decimal 

field. Type integer variable, expression, or constant. 

dest Variable or array of any type or length to contain the 

generated packed field 

isb Byte number within dest specifying beginning location for 

storage. Type integer variable, expression, or constant. 
Bytes are numbered from 1, beginning at the leftmost byte 
position of dest* 

num Number of bytes to be stored. Type integer variable, 

expression, or constant. 



CRAY LOGICAL TO IBM LOGICAL ROUTINE 

The USLCTI subroutine converts Cray logical values into either IBM 
L0GICAL*1 or L0GICAL*4 values. 

Call from FORTRAN: 



CALL USLCTI (sro, dest , isb, num, ten [,inc] ) 



sre Variable or array of any length and of type logical, 

containing Cray logical values to convert 

dest Variable or array of any type or length to contain the 

converted values 

isb Byte number within sre specifying beginning location for 

storage. Type integer variable, expression, or constant. 
Bytes are numbered from 1, beginning at the leftmost byte 
position of src. 
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nwn Number of Cray logical values to convert* Type integer 

variable, expression, or constant. 

ten Size of the IBM logical result value. This value must be 1 

or 4, A value of 1 indicates output logicals are L0GICAL*1 
(8-bit) • A value of 4 indicates output logicals are 
L0GICAL*4 (32-bit). Type integer variable, expression, or 
constant. 

ine Memory increment for fetching the number to be converted. 

Optional parameter of type integer variable, expression, or 
constant. Default value is 1. 



UNPACK 60-BIT WORDS ROUTINE 

The U6064 subroutine unpacks 60-bit words from Cray 64-bit words. 
Call from FORTRAN: 



CALL \J6064[8ro,'isb,de8t 9 nvtm) 



svo Variable or array of any type or length containing 60-bit 

words as a continuous stream of data 

isb Bit location that is the leftmost storage location for the 

60-bit words. Bit position is counted from the left to 
right with the leftmost bit 0. Type integer variable, 
expression, or constant. 

dest Destination array of any type to contain the unpacked 60-bit 

words, left- justified and zero-filled, in a Cray 64-bit word 

nwn Number of 60-bit words to unpack. Generates this many 

elements of dest. Type integer variable, expression, or 
constant . 



PACK 60-BIT WORDS ROUTINE 

The P6460 subroutine packs 60-bit words into Cray 64-bit words. 
Call from FORTRAN: 

CALL P6460 (sre, dest, isb, num) 
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svc Variable or array of any type or length containing 60-bit 

words, left-justified in a Cray 64-bit word 

dest Destination array of any type to contain the packed 60-bit 

words as a continuous stream of data 

i&b Bit location that is the leftmost storage location for the 

60-bit words. Bit position is counted from the left to 
right with the leftmost bit 0. Type integer variable, 
expression, or constant. 

num Number of 60-bit words to pack. Reads this many elements of 

are. Type integer variable, expression, or constant. 



PACK 32-BIT WORDS ROUTINE 

The P32 subroutine packs 32-bit words into Cray 64-bit words. 
Call from FORTRAN: 

CALL P32 (src , dest , num) 

sre Variable of any type or length containing 32-bit words, 

left-justified in a Cray 64-bit word 

dest Destination array of any type to contain the packed 32-bit 

words as a continuous stream of data 

num Number of 32-bit words to pack. Reads this many elements of 

src m Type integer variable, expression, or constant. 



UNPACK 32-BIT WORDS ROUTINE 

The U32 subroutine unpacks 32-bit words from Cray 64-bit words. 
Call from FORTRAN: 

CALL U32 (are, dest, num) 

svc Variable or array of any type or length containing 32-bit 

words as a continuous stream of data. Unpacking always 
starts with the leftmost bit of ere* 
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dest Destination array of any type to contain the unpacked 32-bit 

words, left-justified and zero-filled, in a Cray 64-bit word. 

num Number of 32-bit words to unpack. Generates this many 

elements of dest* Type integer variable, expression, or 
constant . 



CDC INTEGER TO CRAY INTEGER ROUTINE 

The INT6064 subroutine converts CDC 60-bit integer numbers to Cray integer 
numbers. 

Call from FORTRAN: 



CALL INT6064 (arc, idest,num) 



sro Variable or array of any type or length containing CDC 

60-bit integers, left- justified in a Cray 64-bit word 

idest Variable or array of type integer to contain the converted 
values 

num Number of CDC integers to convert. Type integer variable, 

expression, or constant. 



CDC SINGLE-PRECISION TO CRAY SINGLE-PRECISION ROUTINE 

The FP6064 subroutine converts CDC 60-bit single-precision numbers to Cray 
64-bit single^precision numbers. 

Call from FORTRAN: 



CALL FP60 64 (fpn,dest r num) 



fpn Variable or array of any type or length containing CDC 

60-bit, single-precison numbers, left-justified in a Cray 
64-bit word 

dest Variable or array of type real to contain the converted Cray 

64-bit, single-precision numbers 

num Number of CDC single-precision numbers to convert. Type 

integer variable, expression, or constant. 
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CDC DISPLAY CODE CHARACTER TO ASCII CHARACTER ROUTINE 

The DSASC subroutine converts CDC display code characters to ASCII data* 
Call from FORTRAN: 



CALL DSASC (sre,se,dest,nwn) 



are Variable or array of any type or length containing CDC 

display code characters (64 character set) , left-justified 
in Cray 64-bit word. Contains a maximum of 10 display code 
characters per word. 

so Display code character position to begin the conversion* 

Leftmost position is 1. 

dest Variable or array of any type or length to contain the 

converted ASCII data. Results are packed 8 characters per 
word. 

num Number of CDC display code characters to convert. Type 

integer variable/ expression, or constant. 



CRAY INTEGER TO CDC INTEGER ROUTINE 

The INT6460 subroutine converts Cray 64-bit integer numbers to CDC 60-bit 
integer numbers. 

Call from FORTRAN: 



CALL INT6460 (in, ides t, num} 



in Variable or array of any length and of type integer 

containing Cray integer numbers 

idest Variable or array of type integer to contain the converted 
CDC integer numbers. Each integer is left- justified and 
zero-filled. 

num Number of Cray integers to convert. Type integer variable, 

expression, or constant. 
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CRAY SINGLE-PRECISION TO CDC SINGLE-PRECISION ROUTINE 



The FP6460 subroutine converts Cray 64-bit single-precision numbers to CDC 
60-bit single-precision numbers. 

Call from FORTRAN : 



CALL PP6460 (fpn,dest 9 num) 



fpn Variable or array of any length and of type real containing 

Cray single-precision numbers 

dest Variable or array of type real to contain the converted CDC 

60-bit single-precision numbers. Each floating-point number 
is left-justified. 

num Number of Cray single-precision numbers to convert. Type 

integer variable , expression, or constant. 



ASCII CHARACTER TO CDC DISPLAY CODE CHARACTER ROUTINE 

The ASCDC subroutine converts ASCII data to CDC display code characters. 
Call from FORTRAN: 



CALL ASCDC (sra, so tdest, num) 



sro Variable or array of any type or length containing ASCII data 

so ASCII character position to begin the conversion. Leftmost 

position is 1. 

dest Variable or array of any type or length to contain the 

converted CDC display code characters (64 character set) . 
Results are packed into continuous strings without regard to 
word boundries. 

num Number of ASCII characters to convert* Type integer 

variable r expression , or constant. 
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DATASET CONTROL ROUTINES 



The dataset control routines described in this subsection are utilities 
that perform the following dataset processes. 



• 


Opening 


• 


Closing 


• 


Inquiry 


• 


Copying 


• 


Skipping 


• 


Positioning 


• 


Termination 


• 


I/O status reporting 


• 


Auxiliary namelist access 



OPEN DATASET ROUTINE 

The OPEN dataset routine connects an existing dataset to a unit, creates a 
dataset that is preconnected, creates a dataset and connects it to a unit, 
or changes certain specifiers of a connection between a dataset and a 
unit* (For more information on the OPEN dataset routine, see FORTRAN 
(CFT) Reference Manual, CRI publication SR-0009.) 

Call from FORTRAN: 



CALL OPEN (talis*) 



iolist An external unit specifier and, at most, one of each of the 
other specifiers described in table 5-2. 



CLOSE DATASET ROUTINE 

The CLOSE dataset routine terminates the connection of a dataset to a 
unit. (For more information on the CLOSE dataset routine, see FORTRAN 
(CFT) Reference Manual, CRI publication SR-0009.) 

Call from FORTRAN: 



CALL CLOSE (cllist) 



cllist An external unit specifier and, at most, one of each of the 
other specifiers described in table 5-3. 
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INQUIRE ROUTINE 



The INQUIRE routine returns the status of a unit or a dataset. (For more 
information on the INQUIRE routine, see FORTRAN (CFT) Reference Manual r 
CRI publication SR-0009.) 

Call from FORTRAN: 



CALL INQUIRE (Hist) 



iliat A list of specifiers described in table 5-4. 



DATASET COPYING ROUTINES 

Dataset copying routines copy records and files from one dataset to 
another . 



Copy records 

COPYR copies a specified number of records from one dataset to another 
starting at the current dataset position. Following the copy, the 
datasets are positioned after the end-of-record for the last record 
copied. 

Call from FORTRAN t 



CALL COPYR (idn , odn , record [ , is tat ] ) 



idn Dataset name or unit number of dataset to be copied 

odn Dataset name or unit number of dataset to receive the copy 

record Number of records to be copied 

istat A 2-element integer array that returns the number of 

records copied in the first element and number of files 
copied (always 0) in the second element, istat is an 
optional parameter. If present, only fatal messages are 
written to the logfile. 
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Table 5-2 » OPEN specifiers and their meanings 



Specifier 


Data Type 


Meaning 


Input (I) or Return value (RV) 


UNIT-t/ 


Integer 


External unit specifier 


(I) 

Unit number 


IOSTAT*ioa 


Integer variable 
or array element 


Error status specifier 


(RV) 

0 if no error condition exists. 
If error condition exists, error 
message number that corresponds 
to error (see CRAY-OS Message 
Manual, publication £RH)039 for 
error message descriptions.) 


ERR-8 


Statement label 


Statement label where 
control is transferred 
if error condition exists 


(I) 

FORTRAN statement label 




Character expression 


Pile specifier 


(I) 

Name of dataaet to be connected 


STATUS- sta 


Character expression 


Disposition specifier 
(Default, 'UNKNOWN') 


(I) 

•OLD' , dataset must exist and 
FILE" must be specified. 
•NEW', dataset is created, 
status become e 'OLD', FILE* 
must be specified. 
•SCRATCH 1 , dataset is deleted 
when CLOSE statement is 
executed or when program is 
terminated. Dataset must not 
be named. 

'UNKNOWN', the status is 
•SCRATCH 1 if no file specifier 
is supplied and the unit is not 
connected; otherwise, the status 
becomes 'OLD'* 


*£CESS*aco 


Character expression 


Access specifier 
(Default, 'SEQUENTIAL*) 


(I) 

'SEQUENTIAL 1 is access method; 
'DIRECT 1 is access method. 


FORM*///* 


Character expression 


Form specifier (Default, 
'UNFORMATTED' if access 
is direct; 1 FORMATTED ' 
if access is sequential.) 


(1) 

•FORMATTED' , formatted I/O; 
'UNFORMATTED* , unformatted I/O. 


RECL-rl 


Positive integer 
expression 


Record length for direct 
access method (omitted 
for sequential access) 


(I) 

For formatted I/O, number of 
characters per record; 
For unformatted I/O, 8 times the 
number of words. 


BLANK«2>l*fc 


Character expression 


Blank specifier 
(Default, 'NULL') 


(I) 

'NULL' if numeric input blanks 
are ignored; 1 ZERO * if all 
non leading blanks are treated as 
zeros. This specifier permitted 
on datasets opened for formatted 
I/O only. 



t UNIT= does not need to be included in the unit specification 

if u is the first item in otist+ 
ft CFT allows formatted and unformatted records in the same 

dataset (non-ANSI) . 
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Specifier 


Data Type 


Meaning 


Input <I) or Return value (RV) 


UNIT*U f 


integer 


External unit specifier 


(I) 

Unit number 


lOfiTAT-tOS 


Integer variable 
or array element 


Erroc etatus specifier 


<«v> 

0 if no error condition exists; 
If error condition exists, error 
message number that corresponds to 
error (see CRAY-OS Message Manual , 
publication SR-0039 for error 
message descriptions) * 


ERR' 8 


statement label 


Statement label where 
control is transferred 
if error condition exists 


(I) 

FORTRAN statement label 


STATUS "Bit d 


Character expression 


Disposition specifier 
(Default, 'KEEP' if OPEN 
status is 'OLD', 'NEW', 
or 'UNKNOWN* . Default, 
'DELETE; if OPEN Status 
is 'SCRATCH' or dataset 
is memory resident.) 


<I> 

'KEEP', the dataset continues to 
exist after CLOSE statement 
execution. Do not specify 'KEEP* 
for a dataset with ' SCRATCH * 
status on an open statement. 
'DELETE', the data Set does not 
exist after execution of the 
close statement. 



t UNIT= does not need to be included in the unit specification 
if u is the first item in oVlist. 



Copy files 

COPYF copies a specified number of files from one dataset to another, 
starting at the current dataset position. Following the copy f the 
datasets are positioned after the end of file for the last file copied. 

Call from FORTRAN: 



CALL CQVYF(idn r odn,file[, istat]) 



idn Dataset name or unit number of dataset to be copied 

odn Dataset name or unit number of dataset to receive the copy 

file Number of files to be copied 

istat A 2-element integer array that returns the number of 

records copied in the first element and number of files 
copied in the second element, istat is an optional 
parameter. If present, only fatal messages are written to 
the logfile. 
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Table 5-4. INQUIRE specifiers and their meanings 



Specifier 


Data Type 


Meaning 


Input (1) or Return value <RV) 


IGSTAT^ios 


I n tege r variable 
or array element 


Error status specifier 


(RV) 

0 if no error condition exists* If error 
condition exists, error message number that 
corresponds to error {see CRAY— OS Message 
Manual, publication SR-0039 for error message 
descr iptions . ) 


ERR s 0 


5 1 d- t effien t X oDe X 


Statement label 
where control is 
transfer red if error 
condition exists 


(I) 

FORTRAN statement label 


EXlST»ex 


Logical variable 
or array element 


Existence specifier 


(RV) 

•TRUE, if unit or file exists; else, .FALSE. 


OPENED-<?rf 


Logical variable 
or array element 


Connection specifier 


(RV) 

.TRUE, if unit and dataset are connected? 
else, .FALSE. 




Integer variable 
or array element 


External unit specifier 


(RV) 

Unit currently connected; if no unit? wujw i$ 
undefined 


NAMED »«wf 


Logical variable 
or array element 


Unit name specifier 


<KV) 

.TRUE, if unit has a name; else, .FALSE. 




xnirC^jt?x veil x aui^r 

or array element 


Record length of unit 
or file connected for 
direct access 


Record length in characters. (For unformatted 
I/O, the record length is a positive integer 
multiple of eight.) If not connected for 

H 1 i"»r*f" jtrcf^tm . tvO is undefined. 


NEXTRBC-nJ* 


integer variable 
or array element 


Next record 


(RV) 

The record number that follows the last 
record read or written for direct access. 
If none have been written, nr-1* If access 
is not direct, nr is undefined. 


NAME-/* 


Character variable 
or array element 


File name 


(RV) 

File name if file has a name; elfie, fn is 
undefined. 


ACCESS»aff<? 


Character variable 
or array element 


Access specifier 


<KV) 

1 sequential 1 is access methodf •DIRECT' is 
access method* 


SEQUENTIAL* 

ff€<J 


Character variable 
or array element 


Sequential as possible 
access method 


(RV) 

1 YES * if sequential is allowed; 'NO' if 
sequential is not allowed; 'UNKNOWN' if 

UliaDX ^ w tic kBtillXXlC ■ 




Character variable 
or array element 


Direct as possible 
access method 


(RV) 

'YES * if direct is allowed; 
'NO* if direct is not allowed; 
"UNKNUniv it una Die to aeternune* 


FORM-/// 


Character variable 
or array element 


Format specifier 


(RV) 

'FORMATTED' if file is connected for 
formatted I/O? 'UNFORMATTED' if file is 
connected for unformatted I/O. 


FORMATTED- 

frnt* 


Character variable 
or array element 


Formatted as a possible 
allowed form 


(RV) 

'YES' if formatted is allowed; 
'NO' if formatted is not allowed; 
'UNKNOWN' if unable to determine. 


UNFORMATTED 5 * 


Character variable 
or array element 


Unformatted as a 
possible allowed form 


(RV) 

'YES* if unformatted is allowed; 
'NO' if unformatted is not allowed; 
'UNKNOWN * if unable to determine. 


BLANK— 

bUk f 


Character variable 
or array element 


Blank control specifier 


(RV) 

'NULL 1 if null blank control is in effect; 
'ZERO* if zero blank control is in effect. 
Blank control applies only to formatted 
records . 



t CFT allows formatted and unformatted records in the same 
dataset (non-ANSI) . 
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Copy data set 



COPYD copies one dataset to another , starting at their current 

positions. Following the copy, both datasets are positioned after the 

end of file of the last file copied* The end of data is not written to 
the output dataset. 

Call from FORTRAN: 



CALL COPYD (idn,odn [, istat] ) 



idn Dataset name or unit number of dataset to be copied 

odn Dataset name or unit number of dataset to receive the copy 

istat A 2-element integer array that returns the number of 

records copied in the first element and number of files 
copied in the second element, istat is an optional 
parameter. If present, only fatal messages are written to 
the logfile. 



Copy sectors (unblocked) 

COPYU copies either a specified number of sectors or all data to 
end-of-data (EOD) . Copying begins at the current position on both 
datasets. Following the copy, the datasets are positioned after the last 
sector copied. 

Call from FORTRAN: 



CALL COPYU (idn, odn, ns[, is tat]) 



idn Name of unblocked dataset to be copied 

odn Name of unblocked dataset to receive the copy 

ns Decimal number of sectors to copy. If the unblocked 

dataset contains fewer than ns sectors, the copy 
terminates at EOD. If the keyword ns is specified 
without a value, the copy terminates at EOD. The default 
is 1. 

istat An integer array or variable that returns the number of 
sectors copied, istat is an optional parameter. If 
present, only fatal messages are written to the logfile. 
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DATASET SKIP ROUTINES 



The dataset skip routines allow the user to skip a specified number of 
records or files, or a single dataset. 



Skip records 

SKIPR directs the system to bypass a specified number of records from the 
current position of the named blocked dataset 9 

Call from FORTRAN: 



CALL SKIPR (dn,recordl, is tat]) 



dn Dataset name or unit number that contains the record to be 

skipped. Must be a character constant, integer variable, 
or an array element containing Hollerith data of not more 
than seven characters, 

record Decimal number of records to be skipped ♦ The default is 
1. If record is negative, SKIPR skips backward on dn, 

istat A 2-element integer array that returns the number of 

records skipped in the first element and number of files 
skipped (always 0) in the second element, istat is an 
optional parameter* If present, only fatal messages are 
written to the logfile. 

SKIPR does not bypass end-of-f ile (EOF) or beginning of data (BOD) . If 
an EOF or BOD is encountered before record records have been bypassed 
when skipping backwards, the dataset is positioned after the EOF or BOD. 
When skipping forward, the dataset is positioned after the last EOR of 
the current file. 



Skip files 

SKIPF directs the system to skip a specified number of files from the 
current position of the named blocked dataset. 

Call from FORTRAN: 

CALL SKIPF (dn r file [, istat)) 
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dn 



Dataset name or unit number that contains the file to be 
skipped. Must be a character constant, integer variable, 
or an array element containing Hollerith data of not more 
than seven characters. 



file 



Decimal number of files to be skipped. The default is 1. 
If file is negative, SKIPR skips backward on dn. If 
dn is positioned midfile, the partial file skipped counts 
as one file. 



ietat 



A 2-element integer array that returns the number of 
records skipped in the first element and number of files 
skipped in the second element, ietat is an optional 
parameter. If present, only fatal messages are written to 
the logfile. 



SKIPP does not skip end-of-data (EOD) or beg inn ing-of -data (BOD) • If a 
BOD is encountered before file files have been skipped when skipping 
backward, the dataset is positioned after the BOD. When skipping 
forward, the dataset is positioned before the EOD of the current file. 



If the dataset connected to unit FT 07 is positioned just after an 
end-of-file, the following FORTRAN call positions the dataset after the 
previous end-of-file. If the dataset is positioned midfile, it is 
positioned at the beginning of that file. 



CALL SKIPF( , FT07 , ,-1) 



Skip dataset 

SKIPD directs the system to position a blocked dataset at end-of-data 
(EOD), that is, after the last end-of-file of the dataset. If the 
specified dataset is empty or already at EOD, the call has no effect. 

Call from FORTRAN: 



CALL SKIPD {dn I fistat] } 



Example : 
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dn Dataset name or unit number to be skipped* Must be a 

character constant, integer variable , or an array element 
containing Hollerith data of not more than seven characters* 

istat A 2-element integer array that returns the number of 

records skipped in the first element and number of files 
skipped in the second element . istat is an optional 
parameter. If present, only fatal messages are written to 
the logfile. 



Skip sectors (unblocked) 

SKIPU directs the system to bypass a specified number of sectors or all 
data from the current position of the named unblocked dataset* 

Call from FORTRAN: 



CALL SKIPU (dn,ns[, istat]) 



dn Dataset name or unit number of unblocked dataset to be 

bypassed. Must be an integer variable or an array element 
containing ASCII data of not more than seven characters. 

ns Decimal number of sectors to bypass. The default value is 

1. If ns is negative, SKIPU skips backward on dn. 

istat An integer array or variable that returns the number of 
sectors skipped, istat is an optional parameter. If 
present, only fatal messages are written to the logfile. 



DATASET POSITIONING ROUTINES 

Dataset positioning routines change or reflect the position of the 
current dataset. The following positioning routines, except for $GPOS 
and GETPOS, set the current processing direction to input (read) . If the 
previous processing direction is output (write) , end-of-data is written 
on a sequential dataset and the buffer is flushed. On a random dataset, 
the buffer is flushed. 



Get position of mass storage dataset 

The $GPOS routine returns the position of the specified mass storage 
dataset. It determines the current word address of the dataset and can 
return flags indicating that the dataset is positioned at a record, file r 
or dataset boundary. The dataset 1 s position is not altered. 
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The GTPOS%, FDGPOS%, and GETPOS routines return the position of the 
specified interchange tape or mass storage dataset. The dataset' s 
position is not altered. 

Call from CAL: 



CALLV $GPOS 



Entry; 

(Al) Address of Dataset Parameter Table (DSP) or negative DSP 
offset relative to DSP base { JCDSP) , that is, contents of 
second word of Open Dataset Name Table (ODN) 

Exit: 

(Al) DSP address 

(S2) Dataset position 

(SI) Dataset position with flags. (S1)=0 if the dataset is at 

the beginning-of-data (BOD) ; otherwise, the following flags 
are set: 

Bit Description 

0 End-of-record (EOR) flag 

1 Dataset is positioned at a record boundary, that 
is, following a record control word (RCW) . This 
bit is also set if end-of-file (EOF) or 
end-of-data (EOD) bits are set. 

0 Dataset is either at BOD or in the middle of a 
record. 

1 Unused 

2 End-of-file flag. One indicates the dataset is 
at a file boundary, that is, following the 
end-of-file RCW, This bit is also set if the EOD 
bit is set. 

3 End-of-data flag. One indicates the dataset is 
currently at EOD. 

31-63 Word address. This word address is the current 
physical word address within the dataset, 
including RCWs but not including block control 
words (BCW) . 
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GTPOS% obtains, for the CAL user, position information about an opened 
interchange tape dataset. The information returned by GTPOS% refers to 
the last block processed if the dataset is an input dataset. For output 
datasets, the information returned by GTPOS% is meaningless unless the 
tape dataset has been synchronized before the GTPOS% request is made, 
GTPOS% uses call-by-value linkage. 

Call from CAL: 



CALLV GTPOS% 



Entry : 

(Al) Absolute DSP address or negative DSP offset relative to the 
DSP base (JCDSP) 

(A2) Address of tape position information storage area. This 

area must contain LE@TPI words to hold the tape information. 

Exit: 

(Al) Absolute DSP address 

(A2) Address of tape position information storage area. The 

tape position information is returned in fields as defined 
in the Macros and Opdefs Reference Manual, CRI publication 
SR-0012. 

(SI) Return conditions. On exit this register returns errors 
and warnings from the tape get position routine. 

=0 Tape position information successfully returned 
7^0 Error or warning encountered during 
request 

+2 Dataset is not a tape dataset. 



FDGP0S% obtains, for the CAL user, position information about a foreign 
interchange tape or mass storage dataset being processed with the library 
data conversion support (FD parameter on the ACCESS and ASSIGN control 
statements) . The information returned by FDGPOS% is internal information 
to be retained and passed on to a FDSPOS% request. FDGPOS% uses 
call-by-value linkage. 

Call from CAL: 



CALLV FDGPOS% 
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Entry: 

(Al) Absolute DSP address or negative DSP offset relative to the 
DSP base (JCDSP) 

Exit: 

(Al) Absolute DSP address 

(51) Return conditions. On exit this register returns errors 
and warnings from the tape get position routine. 

=0 Tape position information successfully returned 
t^O Error or warning encountered during request; error 

message number; see coded $IOLIB messages in CRAY-OS 

Message Manual , publication SR-0039. 

(52) Dataset position information for finding the beginning of 
the current block (Cray physical record) . For disk 
datasets, this register is set to the Cray block number for 
the sector containing the beginning of the current block. 
For tape datasets, this register is set to the volume block 
count as returned from a TAPEPOS macro request. 

(53) Dataset position information for finding the beginning of 
the current block (Cray physical record) . For disk 
datasets, this register is set to the dataset position, 
including BCWs, of the beginning of the current block. For 
tape datasets, this register is set to the volume serial 
number as returned from a TAPEPOS macro request. 

(54) Dataset position information for finding the beginning of 
the current logical record. For disk and tape datasets, 
this register is set to the current foreign dataset block 
bit length. 



GETPOS returns to the FORTRAN user the current position of the specified 
interchange tape or mass storage dataset. This is a generic routine 
independent of the device medium. The routine does not alter the 
dataset *s position, but captures information that later can be used to 
recover the current position. 

If foreign dataset conversion has not been requested, the physical tape 
block and volume position is determined. For disk datasets, a non-tape 
GETPOS request is made. 

Call from FORTRAN: 



call GETPOS (dn,len,pa[ ,stat}) 



dn Dataset name or unit number 

ten Length in Cray words of the position array. This parameter 

determines the maximum number of position values to 
return. This parameter should be set equal to 3. 
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pa Position array. On exit, pa contains the current 

position information. This information should not be 
modified by the user. It should be retained to be passed 
on to the SETPOS routine. 

stat Return conditions. This optional parameter returns errors 

and warnings from the position information routine* 
=0 Position information successfully returned 
Error or warning encountered during request; 
Error message number; see coded $IOLIB messages in 
the CRAY-OS Message Manual, publication SR-0039. 



Set position of dataset 

To set the position of a mass storage dataset, the position must be at a 
record boundary, that is, at BOD or following an EOR or EOF, or before an 
EOD. A dataset cannot be positioned beyond the current EOD. 

The $SPOS%, $ASPOS, and $FSPOS routines set the position of the specified 
interchange tape or mass storage dataset. The STP0S%, FDSP0S%, and 
SETPOS routines set the position of the specified interchange tape or 
mass storage dataset. 

$SPOS synchronously sets the dataset position, and $ASP0S asynchronously 
sets the dataset position. Library routines finish the asynchronous 
positioning ($ASP0S) if necessary. A bit in the Dataset Parameter Table 
(DPTPOS) can be tested to determine if a $FSPOS call is required. 

Call from GAL: 



CALLV $SPOS 
CALLV $ASPOS 



Entry: 

(Al) Address of Dataset Parameter Table (DSP) or negative DSP 
offset relative to DSP base (JCDSP) , that is, contents of 
second word of Open Dataset Name Table (ODN) . 

(SI) Dataset position 

Bit Description 
0-30 Unused 

31-63 Word address. The desired physical word address 
within the dataset aligned on a record boundary. 
Record control words are included. 
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Exit: 

(Al) DSP address 

(SI) Dataset position 

(S6) RCW after which the dataset is 

positioned; (S6)-0 if at BOD, 



$FSPOS finishes the asynchronous dataset positioning request. 
Call from CAL: 

CALLV $FSPOS 



STPOS% positions, for the CAL user, a tape dataset at a particular tape 
block of the dataset. Data blocks on the tape are numbered so that block 
number 1 is the first data block on a tape. Before a tape dataset is 
positioned with STPOS%, the tape must be synchronized with a call to 
SYNCH%. STPOS% uses call-by-value linkage. 

Call from CAL: 



CALLV STPOS% 



Entry : 

(Al) Absolute DSP address or negative DSP offset relative to the 
DSP base (JCDSP) 

(51) Block number request sign. This register must be set to 

■ + f L, '-'L, or ■ 'L. Refer to register S2, the block number 
value register for usage details. 

(52) Block number or number of blocks to forward space or 
backspace from the current position. The direction of the 
positioning is specified by the block number request sign 
register, SI. 

For forward block positioning, set register SI to , + 'L. The 
plus sign is invalid if either the volume number (S4) is 
unsigned or the volume identifier (S5) has been specified. 

For backward block positioning, set register SI to '-'L. 
The minus sign is invalid if either the volume number (S4) 
is unsigned or the volume identifier (S5) has been specified. 

For absolute block positioning, set register SI to ' 'L. 
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(53) Volume number request sign. This register must be set to 
•h-'L, '^ f L, or 1 "L. Refer to volume number value register , 
S4, for usage details, 

(54) Volume number or number of volumes to forward space or 
backspace from the current position. This parameter should 
be set equal to a binary volume number or number of volumes 
to forward space or backspace. The direction of the 
positioning is specified by the volume number request sign 
register , S3. This parameter is invalid if the volume 
identifier (S5) has also been specified. 

For forward volume positioning, set register S3 to f + f L. A 
block request (register S2) must not be specified with plus 
or minus signs. 



For backward volume positioning, set register S3 to '-'L. A 

block request (register S2) must not* be specified with plus 
or minus signs. 

For absolute volume positioning, set register S3 to 1 'L. 

(S5) Volume identifier to be mounted. This parameter is invalid 
if number of volumes (register S4) has also been requested. 
Also a block request (register S2) must not be specified 
without plus or minus signs. The volume identifier must be 
of the form 'VOX^L. 

Exit; 

(Al) Absolute DSP address 

(SI) Return conditions. On exit this register is used to return 
errors and warnings from the tape get position routine. 
-0 Tape successfully positioned 

Error or warning encountered during request 
-1 Set tape position parameter error 
+2 Dataset is not a tape dataset. 
+3 Positioning request not fully satisfied 



FDSPOS% positions, for the CAL user, a foreign interchange tape or mass 
storage dataset being processed with the library data conversion support 
(FD parameter on the ACCESS or ASSIGN control statements) . FDSPOS% 
returns to the positions retained from a FDGPOS% request. FDSPOS% uses 
call-by-value linkage. 

Call from CAL: 



CALLV FDSPOS% 
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Entry: 

(Al) Absolute DSP address or negative DSP offset relative to the 
DSP base (JCDSP) 

(52) Dataset position information for finding the beginning of 
the current block (Cray physical record) . For disk 
datasets, this register is set to the Cray block number for 
the sector containing the beginning of the current block. 

For tape datasets, this register is set to the volume block 
count as returned from a TAPEPOS macro request. 

(53) Dataset position information for finding the beginning of 
the current block (Cray physical record) . For disk 
datasets, this register is set to the dataset position, 
including BCWs, of the beginning of the current block. For 
tape datasets, this register is set to the volume serial 
number as returned from a TAPEPOS macro request. 

(54) Dataset position information for finding the beginning of 
the current logical record. For disk and tape datasets, 
this register is set to the current block bit length. 

Exit: 

(Al) Absolute DSP address 

(SI) Return conditions. On exit this register returns errors and 
warnings from the tape get position routine. 

-0 Tape position information successfully returned 
7*0 Error or warning encountered during request; error 
message number; see coded $IOLIB messages in CRAY-OS 
Message Manual, publication SR-0039* 



SETPOS allows the FORTRAN user to return to the position retained from the 
GETPOS request. This is a generic routine independent of the device 
medium. SETPOS can be used on interchange tape or mass storage datasets. 

SETPOS positions to a logical record when processing a foreign file with 
the library data conversion support (FD parameter on the ACCESS and ASSIGN 
control statements) . This same capability also exists for mass storage 
files that have been assigned foreign dataset characteristics. 

If foreign dataset conversion has not been requested, the physical tape 
block and volume position is determined. A non-tape SETPOS request is 
made for disk datasets if foreign conversion has not been specified. 

For interchange tape datasets, SETPOS must synchronize before the dataset 
can be positioned. Thus, for input datasets, the dataset must be 
positioned at a Cray end-of -record. An end-of-record is added to the end 
of data before the synchronization if the dataset is an output dataset and 
the end of the tape block was not already written. 
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Call from FORTRAN: 



CALL SETPOS (dn,len,pa[,8tat)) 



dn Dataset name or unit number 

ten Length in Cray words of the position array. This parameter 

determines the maximum number of position values to process 
and allows for the addition of more information fields while 
ensuring that existing codes continue to run. This 
parameter should be set equal to 3. 

pa Position array. On entry, pa contains the desired 

position information from the GETPOS call. 

etat Return conditions* This optional parameter returns errors 

and warnings from the position routine. 
«0 Dataset successfully positioned 
^0 Error or warning encountered during request; 

Error message number; see coded $IOLIB messages in the 
CRAY-OS Message Manual, publication SR-0039. 



Backspace one record 

The $BKSP and BACKSPACE routines position the dataset after the previous 
end-of-record (EOR) . The function is nonoperational if the dataset is at 
beg inning-of -data (BOD) . If the dataset is at the first record of a file, 
these routines position the dataset before the end-of-f ile (EOF) ♦ 

Call from CAL: 



CALLV $BKSP 



Entry: 

(Al) Address of Dataset Parameter Table (DSP) or, if negative, 

DSP offset relative to DSP base (JSDSP) . The second word of 
Open Dataset Name Table (ODN) also contains this negative 
value. 

Exit: 

(Al) Address of DSP 

(S6) Contains record control word (RCW) after which dataset is 
positioned (equals 0 if at BOD} 
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Call from FORTRAN (also clears UEOF flag in the DSP) : 



BACKSPACE {{fin )) 
yalist) 



dfin ) 



u Unit identifier 

fin File identifier whose value specifies the name of the file 

aliet The following set of identifiers: 

[UNIT]=tt 
IOSTAT=i<?S 
ERR-S 

Must contain a single external unit specifier and can 
contain, at most, one of each of the other specifiers. See 
the UNIT, IOSTAT, and ERR specifiers described for the OPEN 
or CLOSE statement, table 5-2 or table 5-3, 



The FDBKSP% routine allows a CAL user to backspace a logical record on a 
foreign interchange tape or mass storage dataset being processed with the 
library data conversion support. 

Call from CAL: 



CALLV FDBKSP% 



Entry : 

(Al) Absolute DSP address or negative DSP offset relative to the 
DSP base (JCDSP) 

Exit: 

(Al) Absolute DSP address 

(SI) Return conditions. On exit this register returns errors 
and warnings from the tape get position routine. 

"0 Tape position information successfully returned 
f*Q Error or warning encountered during request? error 
message number; see coded $IOLIB messages in CRAY-OS 
Message Manual, publication SR-0039. 
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Backspace one file 



The $BKSPF and BACKPILE routines position a dataset after the previous 
end-of-file (EOF) ♦ The function is nonoperational if the dataset is at 
beginning~of-data (BOD) . 

Call from CAL: 



CALLV $BKSPF 



Entry : 

(Al) Address of Dataset Parameter Table (DSP) or r if negative, 
DSP offset relative to DSP base ( JCDSP) • The second word 
of Open Dataset Name Table (ODN) also contains this 
negative value. 

Exit : 

(Al) Address of DSP 

(S6) Contains record control word (RCW) after which dataset is 
positioned (equals 0 if at BOD) 

Call from FORTRAN (also clears UEOF flag in DSP) : 



CALL BACKFILE (dn) 



dn Dataset name or unit number 



Rewind dataset 

Rewind routines rewind a sequential access dataset. 
Call from CAL: 



CALLV $REWD 



Entry: 

(Al) Address of Dataset Parameter Table (DSP) or, if negative, 
DSP offset relative to DSP base (JCDSP) • The second word 
of Open Dataset Name Table (ODN) also contains this 
negative value. 

Exit: 

(Al) Address of DSP 
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Call from FORTRAN: 







REWIND ( 


fin \) 




. alistj 



u Unit identifier. If the dataset is $IN, the file is 

positioned after the first EOF. Otherwise , it is 
positioned at BOD, 

fin File identifier whose value specifies the name of a file 

alist The following set of specifiers must contain a single 

external unit specifier and can contain, at most, one of 
each of the other specifiers. 

[UNIT] -u 

IOSTAT=ios 

ERR=a 

See the UNIT, IOSTAT, and ERR specifiers described for the 
OPEN or CLOSE statement, table 5-2, or table 5-3. 



Position dataset 

$PBN and $APBN position a dataset to a specific block, update DPOUT of 
DSP, clear DPRCW of DSP, and update DPIN of DSP, if a read is from disk. 
$PBN synchronously positions the dataset; $APBN asynchronously positions 
the dataset. 

Call from CAL: 



CALL $PBN 
CALL $APBN 



Entry : 

(Al) Address of Dataset Parameter Table (DSP) 
(A4) Block number 
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NOTE 



A dataset must be in read mode or positioned after a 
$WEOD call* If a disk read was done without recall 
(asynchronous), the user is responsibile for checking 
on completion of the read and any outstanding errors. 
The only valid exit value is the DSP address found in 
Al. 



Exit: 

(Al) Address of DSP 
(A4) New block number 
(A5) DPFRST from DSP: 

(SO) 0 (asynchronous) . Disk read required and recall not 

requested 

1 (synchronous). Disk read not required, or disk read 
required and recall requested 
(S3) DPOUT from DSP 



$PRCW positions dataset after a record control word (RCW) . The dataset 
is positioned after end-of -record in record mode and after end-of-file in 
file mode. The dataset must already be positioned at the block control 
word (BCW) for the block containing the RCW* 

Call from CAL: 



CALLV $PRCW 



Entry : 

(Al) Address of Dataset Parameter Table (DSP) 
(A4) DPOBN from DSP 
(S3) DPOUT from DSP 

(55) Open Dataset Name Table (ODN) (word address including block 
control words) 

(56) Mode<0: Record mode 

>0: File mode 

Exit: 

(Al) Address of DSP 

(S6) RCW after which dataset is positioned (0 if at BOD) 
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Synchronize tape dataset 



SYNCH% synchronizes a CAL program and an interchange tape dataset. If the 
dataset is synchronized for input f the tape must be positioned at the end 
of a block (Cray end-of-record) . However, if the dataset is an output 
dataset and a Cray end-of -record has not been written, the SYNCH% routine 
writes an EOR before synchronizing. For an output tape, control is not 
returned to the user until all of the data in the circular I/O buffer has 
been written to the tape. SYNCH% uses call-by-value linkage. 

Call from CAL: 



CALLV SYNCH% 



Entry: 

(Al) Absolute DSP address or negative DSP offset relative to the 

DSP base (JCDSP) 
(SI) Processing direction: 

=0 Input dataset 

=1 Output dataset 

Exit: 

(Al) Absolute DSP address 

(SI) Return conditions. On exit this register returns errors and 
warnings from the synchronization routine. 
=0 Tape successfully synchronized 
^0 Error or warning encountered during request 
+1 Execution error; the error code is in DPERR field of 

DSP table. 
+2 Dataset is not a tape dataset. 



DATASET TERMINATION ROUTINES 

The $WEOF, $WE0D, EODW, ENDFILE, and $EOFR routines terminate datasets by 
writing end -of -record (EOR) and end-of-f ile (EOF) , or EOR, EOF, and 
end-of-data (EOD) . 

$WEOF writes an EOF preceded by an EOR, if necessary, as the next words in 
the I/O buffer. 

$WEOD writes an EOD preceded by an EOR and an EOF, if necessary, as the 
next words in the I/O buffer. The $WE0D forces the final block of data to 
be written on the disk; that is, it flushes the I/O buffer. The dataset 
is left positioned before the EOD. 
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Call from CAL: 



CALLV $WEOF 
CALLV $WEOD 



Entry t 

(Al) Address of Dataset Parameter Table (DSP) or, if negative, 

DSP offset relative to DSP base (JCDSP) . The second word of 
Open Dataset Name Table (ODN) also contains this negative 
value. 

Exit; 

(Al) Address of DSP 



EODW writes EOD, EOF, and EOR, if necessary, and clears the UEOF flag in 
the DSP. 

Call from FORTRAN : 



CALL EODW(<frz) 



dn Dataset name or unit number 



ENDFILE writes EOF and EOR, if necessary, on sequential access file and 
clears UEOF flag in DSP. 

Call from FORTRAN: 



ENDFILE (dn I , iostat, err] ) 



dn Dataset name or unit number 

iostat Address of IOSTAT parameter 
err ERR parameter 



$EOFR determines if UEOF flag in DSP is set and clears UEOF flag in DSP. 
Call from CAL: 



CALL $EOFR, (arg) 
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Entry: 

arg Address of dataset name or unit number 
Exit: 

(SI) 0 if UEOP was not set 
1 if UEOF was set 



I/O STATUS ROUTINES 

UNIT returns I/O status upon completion of an I/O operation. 
Call from FORTRAN: 



exit=miT(dn) 



exit -2.0 Operation complete, no errors, partial read, did not 

read EOR (blocked I/O only) 
-1.0 Operation complete, no errors 
0.0 EOF or EOD on last read on blocked dataset s, or 
end-of-information (EOI) on unblocked datasets 
+1.0 Parity error 
+2.0 Unrecovered hardware error 

dn Dataset name or unit number 



LENGTH returns number of words processed in last buffer operation. 
Call from FORTRAN: 



exi LENGTH (dn ) 



exit On exit, word count from last buffer operation or 0 if EOF 

or EOD is encountered 

dn Dataset name or unit number 



I EOF returns integer EOF status and clears UEOF flag in DSP. 
Call from FORTRAN: 



tsxit^IEOF (dn) 
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iexit 



-1 EOD on last operation 

0 Neither EOD nor EOF on last operation 
+1 EOF on last operation 



dn Dataset name or unit number 

EOF returns a real value EOF status and clears UEOF flag in DSP, 
Call from FORTRAN: 



r>exit=EOF (dn) 



rexit -1.0 EOD on last operation 

0.0 Neither EOD nor EOF on last operation 
+1.0 EOF on last operation 

dn Dataset name or unit number 



IOSTAT returns end-of-file status. 
Call from FORTRAN: 



iexi t- IOSTAT {dn ) 



iexit 0 No error 

1 UEOF cleared (EOF) 

2 UEOD cleared (EOD) 

dn Dataset name or unit number 



$EOATEST checks for a read/write past the allocated area condition. If 
such a condition exists f an error message is issued and the job aborted* 

Call from CAL: 

CALLV $EOATEST 



Entry: 

(Al) DSP address 
Exit (if job not aborted) : 

(Al) DSP address 
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SUEOFSET sets the uncleared End-of-f ile flag in the DSP. 
Call from CAL: 



CALLV $UEOFSET 



Entry: 

(Al) DSP address 

Exit: 

(Al) DSP address 



$UEOPTCL clears the uncleared End-of-file flag in the DSP and indicates 
whether it had been set or not. 



Call from CAL: 



CALLV 3UE0FTCL 



Entry: 

(Al) DSP address 
Exit: 

(Al) DSP address 

(SI) 0 # if UEOF was not set 
Nonzero if UEOF was set 



$UEOFKIL aborts job if uncleared End-of-file flag is set in the DSP. 
Call from CAL: 



CALLV SUEOFKIL 



Entry: 

(Al) DSP address 
Exit (if job not aborted): 

(Al) DSP address 



AUXILIARY NAMELIST ROUTINES 

NAMELIST routines allow user control of input and output defaults and are 
accessed by call-by-address subprogram linkage ♦ No arguments are 
returned. For a complete description of the NAMELIST feature, see the 
FORTRAN (CFT) Reference Manual, CRI publication SR-0009. 
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RNLSKIP determines action if NAMELIST group encountered is not the 
desired group. 

Call from FORTRAN : 



CALL RNLSKIP (mode ) 



mode >0 Skip past the group and issue an information 

logf ile message (default) . 
=0 Skip past group. 
<0 Abort job or go to ERR^address. 



RNLTYPE determines the action if a type mismatch occurs across the equal 
sign on an input card. 

Call from FORTRAN; 



CALL RNLTYPE (mode) 



mode -0 Abort job or go to ERR-address. 

^0 Convert constant type to variable type if possible; 
otherwise, abort or go to ERR=address (default) ♦ 

RNLECHO specifies unit for error messages and input echo. 
Call from FORTRAN: 



CALL RNLECHO (unit) 



unit =0 Error messages and echoed input go to $0UT (default) . 

^0 Error messages and echoed input go to specified 
unit. All input is echoed. 

The following four routines (RNLFLAG, RNLDELM, RNLSEP , and RNLCOMM) add 
or delete characters from the set of characters recognized by the 
namelist input routine in various positions, char is a single 
Hollerith character specified in H f C, or R format; it is not a character 
variable. No checks are made to ensure that alternate character 
selections are consistent. 
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RNLFLAG deletes or adds echo character. If an echo character appears in 
column 1 of an input record, that record and all subsequent records 
processed by the current READ, are copied to the echo output unit. 

Call from FORTRAN: 

CALL RNLFLAG /K<?<fe) 

char Echo character. Default is E. 

mode **0 Delete character. 

7*0 Add character. 

RNLDELM deletes or adds NAMELIST group delimiting character. The group 
character is the first character of the group name and the END terminator. 

Call from FORTRAN: 

CALL mimJM{char 9 mode) 

char Delimiting character. Default is $ and &. 

mode =0 Delete character. 

Add character. 

RNLSEP deletes or adds separator character. The separator character 
separates data items in the input records. 

Call from FORTRAN: 

call rnlsep ( chax* , mode ) 

char Separator character. Default is 

mode =0 Delete character. 

^0 Add character. 
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RNLREP deletes or adds replacement character. 
Call from FORTRAN: 



CALL RNLREP (char, mode) 

char Replacement character. Default is *=• 

mode ®0 Delete character. 

Add character* 

RNLCOMM deletes or adds trailing comment indicator. 
Call from FORTRAN; 

CALL RNLCOMM (char,mode) 

char Trailing comment indicator. Default is : and 

mode =0 Delete character. 

5*0 Add character, 

WNLLONG indicates output line length. 
Call from FORTRAN: 

CALL WNLLONG (length) 

length Output line length; 8<length<161 or length*-l (-1 

specifies default of 133 unless the unit is 102 or $PUNCH, 
in which case the default is 80) • 



WNLDELM defines ASCII NAMELIST delimiter. 
Call from FORTRAN: 

CALL WNLDELM (char) 

ohar NAMELIST delimiter. Default is &. 
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WNLSEP defines ASCII NAMELIST separator. 
Call from FORTRAN: 

CALL WNLSEP (char) 

char NAMELIST separator. Default is r . 

WNLREP defines ASCII NAMELIST replacement character ♦ 
Call from FORTRAN: 

CALL WNLREP (char) 

char NAMELIST replacement character. Default is =. 

WNLFLAG indicates the first ASCII character of the first line. 
Call from FORTRAN: 

CALL WNLFLAG {chav) 

char First ASCII character of the first line. Default is blank. 

LOGICAL RECORD I/O ROUTINES 

Logical record I/O routines are normally called by FORTRAN I/O routines 
and communicate with the system through Exchange Processor requests. 

These routines are divided into read, write, CAL I/O interface, 
character, and bad data error recovery routines. 

READ ROUTINES 

Read routines transfer partial or full records of data from the I/O 
buffer to the user data area. Depending on the read request issued, the 
data is placed in the user data area one character per word or in full 
words. (Blank decompression occurs only when data is being read one 
character per word.) In partial mode the dataset maintains its position 
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after the read is executed* In record mode the dataset position is 
maintained after the E0R that terminates the current record* Figure 5-4 
provides an overview of the logical read operation. 



Read words 

Routines transferring full words transmit the words from the I/O buffer 
to the area beginning at the first word address (FWA) . This process 
continues until either the word count in A3 is satisfied or an EOR is 
encountered, 

Unrecovered data errors do not cause the job to abort • Control is 
returned to the user to use the good data that was read, (A2) through 
(A4)-l, and to decide whether to abort or to skip or accept the bad 
data. If the user does nothing, the job is aborted on the next read 
request* 



$RWDP reads words, partial record mode. $RWDR reads words, full record 
mode. 

Call from CAL: 



CALLV $RWDP 
CALLV $RWDR 



Entry: 

(Al) Address of Dataset Parameter Table (DSP) or, if negative, 
DSP offset relative to DSP base ( JCDSP) . The second word 
of Open Dataset Name Table (ODN) also contains this 
negative value. 

(A2) FWA of user data area 

(A3) Word count. If count=0, no data is transferred. 
Exit: 

(Al) Address of DSP 

(A2) FWA of user data area 

(A3) Word count 

(A4) Actual LWA+1 (equals FWA if null record) 

(50) Termination mode: 

<0 Read terminated by EOR 

=0 Null record, EOF, EOD, or unrecovered data error 

encountered 
>Q Read terminated by count. If count is 

exhausted simultaneously with reaching EOR, the EOR 

takes precedence* 

(51) Error status; 

0 No errors encountered 

1 Unrecovered data error encountered 

(S6) Record control word (RCW) if (S0)<0 and (S1)«0 
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I/O BUFFER POINTERS 



DSP 



(A2)- 




SYSTEM 



Figure 5-4. Logical read 
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Example of $RWDP; 



I A | B | C ) D I E | F | G 1 H 1 

IIIJIKILIMIHIOIPI (A2)_ 

|QlR|SlTlUjV|W|X| $RWDP (A3) =2 J" I A 1 B) C|D [ £ I F | G I H | 

I Y 1 Z I A | A | A | A | A | A 1 * t 1 1 |J|K I L |M|N |Q] P 1 

I RCW | 

1011)213141516171 User data area 

I819|A1A|A|A|A1A| 

J RCW L 

Data in I/O buffer 



READ reads words, full record mode, READP reads words, partial record 
mode* 



Call from FORTRAN: 



CALL READ (dn ,word, count , status [ ,ubc] } 
CALL read? (dn, word, count, etatus[ ,ubc]) 



dn 

word 
count 



Dataset name or unit number 



Word-receiving data area 



On entry: number of words requested 

On exit: number of words actually transferred 



status 



ubc 



On exit: 

-1 Words remain in record* 

0 EOR 

1 Null record 

2 EOF 

3 EOD 

4 Unrecovered data error encountered 

Optional unused bit count. On exit, if end of record is 
reached, ubc contains the unused bit count in the last 
word. The unused bits are zeroed in the user's data area* 



Read characters 

Read character routines unpack characters from the I/O buffer and insert 
them into the user data area beginning at the first word address (FWA) . 
This process continues until either the count is satisfied or an EOR is 
encountered. If an EOR is encountered first, the remainder of the field 
specified by the character count is filled with blanks. 
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Unrecovered data errors do not cause the job to abort. Control is 
returned to the user to use the good data that was read, (A2) through 
(A4)-l, and to decide whether to abort, or to skip or accept the bad 
data. If the user does nothing, the job is aborted on the next read 
request* 



$RCHP reads characters, partial record mode. $RCHR reads characters, 
full record mode. 

Call from CAL: 



CALLV $RCHP 
CALLV $RCHR 



Entry: 

(Al) Address of Dataset Parameter Table (DSP) or, if negative, 
DSP offset relative to DSP base ( JCDSP) . The second word 
of Open Dataset Name Table (ODN) also contains this 
negative value. 
(A2) First word address (PWA) of user data area 
(A3) Character count. If count^O, no data is transferred. 
Exit: 

(Al) Address of DSP 

(A2) FWA of user data area 

(A3) Character count 

(A4) Actual LWA+1 (equals FWA if null record) 

(50) Termination mode: 

<0 Read terminated by EOR 

-0 Null record, end-of-file, end-of-data, or unrecovered 

data error encountered 
>0 Read terminated by count. If count is 

exhausted simultaneously with reaching EOR, the EOR 

takes precedence. 

(51) Error status: 

=0 No errors encountered 
=1 Unrecovered data error encountered 
(S6) RCW if (S0)<0 and (S1)»0 
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Example of $RWDP: 



(A2) 



|T|H|r|SU I I|S[A| $RCHP 



IDIAITIAI.IAIAIAI 



Data in I/O buffer 



(A3) =16 



1- 



User data area 



RE ADC reads characters, full record mode* READCP reads characters, 
partial record mode. 



Call from FORTRAN: 



CALL READC (dn , char, count, status) 
CALL READCP (<irz, char, count, status) 



dn Dataset name or unit number 

char Character-receiving data area 

count On entry: Number of characters requested 

On exit: Number of characters actually transferred 

status On exit: 

-1 Characters remain in record. 

0 EOR 

1 Null record 

2 EOF 

3 EOD 

4 Unrecovered data error 
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Read IBM words 

READ IBM reads two IBM 32-bit floating-point words from each Cray 64-bit 
word. 

Call from FORTRAN; 



CALL READ IBM (dn ,fwa,word, increment) 



dn Dataset name or unit number 

fwa First word address (FWA) of user data area 

word Number of words needed 

increment Increment of IBM words read 

On exit, the IBM 32-bit format is converted to the equivalent Cray 64-bit 
value. The Cray 64-bit words are stored in user data area. 



Read unblocked data 

$RLB reads data directly into the user area without the use of system I/O 
buffers, RCWs, or BCWs. 

Call from CAL: 



CALLV $RLB 



Entry: 

(Al) Address of Dataset Parameter Table (DSP) or, if negative, 
DSP offset relative to DSP base (JCDSP) . The second word 
of Open Dataset Name Table (ODN) also contains this 
negative value. 

(A2) First word area (PWA) of user data area 

(A3) Word count. If count=0, no data is transferred. 

(SI) Recall indicator; specifies whether read is done 
synchronously or asynchronously. 

0 No I/O recall requested (asynchronous) 

1 I/O recall requested (synchronous) 

Exit: 

(A1-A3) Unchanged 
If recall requested: 

(SO) -1.0 Operation complete, no errors 

0.0 End-of -information (EOI) on last read 
+1.0 Parity error 
(A4) Actual last word address+1 
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WRITE ROUTINES 

Write routines transfer partial or full records of data from the user 
data area to the I/O buffer* Depending on the write operation requested, 
data is taken from the user data area one character per word and packed 
eight characters per word or is transferred in full words. (Blank 
compression occurs only when data is being written one character per 
word). In partial mode, no EOR is inserted in the I/O buffer to 
terminate the record. In record mode an EOR is inserted in the I/O 
buffer in the next word following the data that terminates the record. 
Figure 5-5 provides an overview of the logical write operation. 



Write words 

In routines where words are written, the number of words specified by the 
count is transmitted from the area beginning at the first word address 
(FWA) and is written in the I/O buffer. 

$WWDP writes words, partial record mode. 

$WWPU writes words, partial record mode with unused bit count. The user 
can specify the unused bit count in the last word of a partial record as 
an entry condition. 

$WWDR writes words, full record mode. 

$WWDS writes words, full record mode with unused bit count. The user can 
specify the unused bit count in the last word of the record as an entry 
condition. 

Call from CAL: 



CALLV $WWDP 
CALLV $WWPU 
CALLV $WWDR 
CALLV $WWDS 



Entry: 

(Al) Address of Dataset Parameter Table (DSP) or, if negative, 
DSP offset relative to DSP base (JCDSP) . The second word 
of Open Dataset Name Table (ODN) also contains this 
negative value. 
(A2) First word address (FWA) of user data area 
(A3) Word count. If count=0, no data is transferred; EOR is 
written. 

(A4) Unused bit count, value 0 to 63 ($WWDS and $WWPU only) 



SR-0014 



5-70 



I 



Exit: 

(Al) Address of DSP 

(A2) FWA of user data area 

(A3) Word count 



Example of $WWDP; 



|A|B|C|D|E|F|G|H| 
UlJlKfLlMjNlOlPl 
IQIRISITIUIVIWIXI 
1YIZ1 | I 1 | | 1 

User data area 



1A1B1C|D|E|F|G1H| 
$WWDP |I| JlKlL|M|NlO|Pl 
^ IQIRISITIUIVIWIXI 

1YIZI I I 1 I I I 

I/O buffer 



WRITE writes words, full record mode. 
Call from FORTRAN: 

CALL WRITE (dn ,word, count [ , ubc] ) 

dn Dataset name or unit number 

word Data area containing words 

count Word count. A value of 0 causes an end-of -record record 
control word to be written. 

ubc Optional unused bit count. Number of unused bits contained 

in the last word of the record. 

WRITEP writes words, partial record mode. 
Call from FORTRAN: 

CALL WRITEP (dn 9 wovd 9 count I , ubo] ) 

dn Dataset name or unit number 

word Data area containing words 

count Word count 

ubo Optional unused bit count. Number of unused bits contained 

in the last word of the record. 
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Figure 5-5. Logical write 
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Write characters 



Write character routines pack characters into the I/O buffer for the 
dataset. The number of characters packed is specified by the count. 
These characters originate from the user area defined at first word 
address (FWA) . 



$WCHP writes characters, partial record mode. 



$WCHR writes characters, full record mode. The unused bit count in the 
record control word (RCW) specifies the EOD in the previous word* 



Call from CAL: 



CALLV $WCHP 
CALLV $WCHR 



Entry: 

(Al) Address of Dataset Parameter Table (DSP) or, if negative, 
DSP offset relative to DSP base (JCDSP) , The second word 
of Open Dataset Name Table (ODN) also contains this 
negative value, 

(A2) FWA of user data area 

(A3) Character count. If count=0, no data is transferred; EOR 
is written. 

Exit: 

(Al) Address of DSP 

(A2) FWA of user data area 

(A3) Word count 



Example of $WCHP: 



<A2) 



(A3) =11 



U 



U 



$WCHP 



I previously I 
I written data I 
I lO|U|T[PlUtTl 



I A ( D | A | T | Af | f | 
I/O buffer 



User data area 
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WRITEC writes characters, full record mode, WRITECP writes characters , 
partial record mode* 

Call from FORTRAN: 

CALL WRITEC {dn , char, count) 
CALL WRITECP {dn , char, coun t) 

dn Dataset name or unit number 

ohav Data area containing characters 

count Character count 

Write IBM words 

WRITIBM writes two IBM 32-bit floating-point words from each Cray 64-bit 
word. 

Call from FORTRAN: 

CALL WRITIBM (<i«,/ya 9 value $ increment) 

dn Dataset name or unit number 

fwa FWA of user data area 

value Number of values to be written 
increment Increment of source (Cray) words written 
On exit, IBM 32-bit words written to unit 

Write unblocked data 

$WLB writes data directly from user area without the use of system I/O 
buffers, RCWs, or BCWs. 

Call from CAL: 
CALLV $WLB 
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Entry: 

(Al) Address of Dataset Parameter Table (DSP) or, if negative , 
DSP offset relative to DSP base (JCDSP} . The second word 
of Open Dataset Name Table (ODN) also contains this 
negative value. 
(A2) First word address (FWA) of user data area 
(A3) Word count* If count=0, no data is transferred, 
(SI) Recall indicator. Specifies whether write is done 
synchronously or asynchronously. 

0 No I/O recall requested (asynchronous) 

1 I/O recall requested (synchronous) 

Exit: 

(A1-A3) Unchanged 
If recall requested: 

(SO) -1.0 Operation complete, no errors 
+1.0 Parity error 

+2.0 Unrecovered hardware error 



CAL I/O INTERFACE ROUTINE 

$CBIO provides buffered I/O interface for CAL requests. The user is 
responsible for ensuring that requested data transfers are complete and 
error free by examining the Dataset Parameter Table (DSP) before 
attempting to process input data or requesting additional writes. 

Call from CAL: 

CALLV $CBIO 



Entry : 

(SI) Address of DSP 



BAD DATA ERROR RECOVERY ROUTINES 

Bad data error recovery routines enable a user program to continue 
processing a dataset when bad data is encountered. Bad data means an 
unrecovered error was encountered while the dataset was being read. 
Skipping the data forces the dataset to a position past the bad data so 
no data is transferred to a user-specified buffer. Accepting the data 
causes the bad data to be transferred to a user-specified buffer and the 
dataset is positioned immediately following the bad data. 

When an unrecovered data error is encountered, the user continues 
processing by calling either SKIPBAD or ACPTBAD. 
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SKIPBAD allows the user to skip the bad data so no bad data is sent to 
the user-specified buffer* 

Call from FORTRAN: 



CALL SKIPBAD (dn f blocks , tevmcnd) 



dn Dataset name or unit number 

blocks On exit, contains the number of blocks skipped. The 

dataset format determines the meaning of block (see the 
CRAY-OS Version 1 Reference Manual, publication SR-0011, 
for definitions of the tape block formats) . The format can 
be : 

• Interchange* Number of physical tape blocks skipped, 

• Blocked transparent* Number of sectors or 512-word 
blocks skipped* 

• Unblocked* Number of sectors or 512-word blocks 
skipped. 

tevmcnd On exit, address of termination condition* For an 

unblocked dataset, only a negative value (not at EOD) or a 
2 (at EOD) is returned* 

<0 Not positioned at a record control word (RCW) 
=0 Positioned at EOR 
>0 If 1, positioned at EOF 
If 2, positioned at EOD 



ACPTBAD makes bad data available to the user by transferring it to the 
user-specified buffer. 

m Interchange. The portion of bad data between the current position 
and the next control word is transferred (no control words are 
transferred) * 

• Blocked transparent. The entire sector or 512-word block 
following the current position is transferred (control words are 
transferred) . The possibility of having a partial block (<512 
words) exists. 

• Unblocked. The entire sector or 512-word block is read into the 
user data area and then transferred to a user-specified buffer. 
The bad data is placed after the good data from the read* The 
user can specify the word address of the user-supplied buffer to 
be the same as the address immediately following the good data. 
This specification prevents transfer to a user-specified buffer. 
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Call from FORTRAN: 



CALL ACPTBAD (dn , uda , wvden t , t evmcnd , ubcnt ) 



dn 



Dataset name or unit number 



uda 



User data area to receive the bad data; length must 
words* 



be 512 



wrdent On exit, number of words transferred (£512) 

termond On exit, address of termination condition. This is defined 



for datasets in interchange and blocked transparent format* 

<0 Not positioned at a record control word (RCW) 
=0 Positioned at EOR 
>0 If 1, positioned at EOF 
If 2, positioned at EOD 



CHARACTER ROUTINES 

Character routines load and store character items, find the beginning of a 
format, and increment character addresses * These routines are used by I/O 
routines. $LCI and $SCI are used by character routines and I/O routines, 
and $FFS and $UIO are used by I/O routines only. 



$LCI loads a character item* 
Call from CAL: 



CALLV $LCI 



ubent 



On exit, address of unused bit count. Only defined 
termination condition is 0, and wvdant is nonzero. 



if 



Entry: 
(SI) 
Exit: 



Character address pointer 



(Al) 
(VL) 
(VI) 
(SI) 



Length of item in words 

Length of item in words 

Character item adjusted to word boundary 

Size in characters 
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$SCI stores a character item. 
Call from GAL: 



CALLV $SCI 



Entry: 
(SI) 
(VI) 



Address of character item 

Place to store , adjusted to word boundary; blank fill 



$FFS finds the start of a format. 
Call from GAL: 



CALLV $FPS 



Entry : 
(SI) 

Exit: 
(AO) 

(Al) 
(A2) 



Address of format 

0 if starting ( is found 

Nonzero if non-numeric character is found before ( 
Word address of starting ( 
Character position of starting ( 



$UIO increments character address. 
Call from CAL: 



CALLV $010 



Entry : 
(SI) 
<S2) 



Address of character address pointers 
Increment between items 



NUMERIC CONVERSION ROUTINES 

Numeric conversion routines convert a character to a numeric format or a 
number to a character format. 
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CAUTION 

$NICV and $NOCV are obsolete* NICV% and NOCVft should 
be used in their place. 

******************************************************* 



NICV% and NICONV perform numeric integer input conversion to character 
format. 

Call from CAL: 



CALLV NICV% 



Entry: 

(Al) First input character address 

(53) Field width (optional) 

(54) Decimal places (optional) 

(55) P factor (optional) 

(56) Mode in bits 49 to 63 (symbols defined in $IOLIB) . See 
table 5-5 for description of bits. 

Exit: 

(Al) Last input character address+1 

(S1,S2) Binary result 

(53) Next character 

(54) Return conditions. See table 5-6 for descriptions. 



Call from FORTRAN: 



CALL mcowj{fca 9 fw f dp 9 pf 9 mode 9 br r stat) 



fca First input character address; on exit, last input character 
address +1 

fu Field width in characters 

dp Decimal places 

pf P factor 

mode Conversion mode. See table 5-5 for description of bits. 
SR-0014 5-79 I 



bv High-order binary result followed by low-order binary 

result. This parameter must be two Cray 64-bit words long. 

stat Errors and warnings returned from the conversion routines. 

See table 5-6 for descriptions. 



Table 5-5. Conversion mode descriptions 



Bit 


Symbol 


Description 


49 


SVDPART 


Set if decimal places field present 


50 


SVCFT 


Set if called from library; 0 if 
called from CFT. 


51 


SVPLS 


Set if requested + sign output 


52 


SVEXPS 


Set if exponent size defined 


53 


SVSEXP 


Sign of exponent 


54 


SVSMAN 


Sign of fraction or number 


55 


SVDFLD 


D conversion 


56 


SVGFLD 


G conversion 


57 


SVEFLD 


E conversion 


58 


SVFFLD 


F conversion 


59 


SVIFLD 


I conversion 


60 


SVZFLD 


Hex conversion 


61 


SVOFLD 


Octal conversion 


62, 63 


SVBZR,SVBNL 


Blank conversion indicators: 

00 Blanks treated as delimiters 

01 Blanks ignored (as in 
FORTRAN source) 

10 Blanks treated as zeros (as 
in FORTRAN run- time input) 



N0CV% and NOCONV perform numeric output conversion. 
Call from CAL: 



CALLV NOCV% 



Entry: 

(Al) First output character address 

(A2) Size of exponent (if SVEXPS bit set) 

(SI) , (S2) Binary number to be output 

(53) Field width 

(54) Decimal places 
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(55) P factor 

(56) Mode in bits 49 to 63 (symbols defined in $IOLIB) . See 
table 5-5 for description of bits. 

Exit: 

(Al) Last output character address 



Table 5-6. Conversion return conditions 



Mode 


Description 


O'0077 


Typeless 


O'4027 


24-bit integer 


O'4077 


64-bit integer 


O'6077 


64-bit real 


0'6177 


128-bit real 


-1 


Illegal character 


-2 


Overflow 


-3 


Exponent underflow 


-4 


Exponent overflow 


-5 


Null field 



Call from FORTRAN: 



call NOCONV (fca 9 fw , dp 9 pf,mode , sexp , bv , status 



fea First output character address; on exit, last output 

character address. 

fw Field width in characters 

dp Decimal places (cannot apply to conversion) 

pf P factor 

mode Conversion mode. See table 5-5 for bit descriptions. 

sexp Size of exponent if Mode flag is set 

br Binary number to be converted. High-order binary value 

followed by the low-order value. This parameter must be 
two Cray 64-bit words long. 
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stat Errors and warnings returned from the conversion routines 

^0 No error in conversion 

<0 Error in conversion. (Current version of numeric 

output conversion has no error conditions to return.) 



$NICV performs numeric input conversion. This routine is obsolete. 
Call from CAL: 



R $NICV 



Entry: 

(A3) Field width (optional) 

(A4) Decimal places (optional) 

(A5) P factor (optional) 

(A6) First character address 

(S6) Mode in bits 49 to 63 (symbols defined in $IOLIB) . See 
table 5-5 for bit descriptions. 

Exit: 

(Al) Next character 

(A2) Mode (in octal). See table 5-6 for descriptions. 

(A6) Last input character address+1 

(51) High-order result 

(52) Low-order result 



$N0CV performs numeric output conversion. This routine is obsolete. 
Call from CAL: 



R $N0CV 



Entry : 

(A3) Field width 

(A4) Decimal places 

(A5) P factor 

(A7) First output character address 

(SI) , (S2) Binary number to be output 

(S6) Conversion mode in bits 49 to 61 (symbols defined in 
$IOLIB) . See table 5-5 for bit descriptions. 

Exit: 

(A7) Last output character address 
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RANDOM ACCESS DATASET I/O ROUTINES 



Sequentially accessed datasets are used for applications that read input 
to a job once at the start of the process and write output to a job once 
at the end of the process. However, when large numbers of intermediate 
results are used randomly as input in later stages of jobs, a random 
access dataset capability is more efficient to use than sequential 
access. A random access dataset consists of records that are accessed and 
changed in the same manner. Random access of data removes the slow 
processing and inconvenience of sequential access, particularly when the 
order of reading and writing records differs in various applications or 
when I/O speed is important. 

Random access dataset I/O routines allow the user to specify how records 
of a dataset are to be changed without the usual limitations of sequential 
access. Only those I/O routines meant for each type of dataset can be 
used with predictable results. 

Random access datasets can be created and accessed by the 
record-addressable dataset routines (READMS/WRITMS f RE ADDR/WR I TDR ) or the 
word-addressable dataset routines ( GETOA/PUTWA) . 



NOTE 

Generally, random access dataset I/O routines used in a 
program with overlays or segments should reside in the 
root segment or first overlay. However, if all I/O is 
done within one overlay, the routines can reside in 
that overlay. If all I/O is done in that overlay's 
successor, the routines can reside in the successor 
overlay. 



RECORD-ADDRESSABLE , RANDOM ACCESS DATASET I/O ROUTINES 

Record-addressable, random access dataset I/O routines allow the user to 
generate datasets containing variable-length, individually addressable 
records. These records can be read and rewritten at the user's 
discretion. The library routines update indexes and pointers. 

The random access dataset information is stored in two places: in an 
array in user memory and at the end of the random access dataset. 
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When a random access dataset is opened, an array in user memory contains 
the master index to the records of the dataset* This master index 
contains the pointers, and optionally the names of the records within the 
dataset. Although this storage area is provided by the user, it must be 
modified only by the random access dataset I/O routines. 

When a random access dataset is closed and optionally saved, the storage 
area containing the master index is mapped to the end of the random 
access dataset, thus recording changes to the contents of the dataset* 

The following FORTRAN-callable routines can change or access a 
record-addressable, random access dataset: OPENMS, WRITMS, READMS , 
CLOSMS, FINDMS, CHECKMS, WAITMS, ASYNCMS, SYNCMS, OPENDR, WRITDR, READDR, 
CLOSDR, STINDR, CHECKDR, WAITDR, ASYNCDR, SYNCDR and STINDX. 

The READDR/WRITDR random access I/O routines are direct-to-disk versions 
of READMS /WRITMS . All input or output goes directly to or from the 
user's data area from or to the mass storage dataset without passing 
through a system maintained buffer in high memory* Since mass storage 
can only be addressed in even 512 word blocks, all record lengths are 
rounded up to the next multiple of 512 words* 

Users can intermix both READMS /WRITMS and READDR/WRITDR datasets in the 
same program. Do not use the same file in both packages at the same time. 

OPENMS/OPENDR opens a local dataset and specifies the dataset as a random 
access dataset that can be accessed or changed by the record-addressable, 
random access dataset I/O routines. If the dataset does not exist, the 
master index contains zeros; if the dataset does exist, the master index 
is read from the dataset. The master index contains the current index to 
the dataset. The current index is updated when the dataset is closed 
using CLGSMS/CLOSDR. 

A single job can use up to 40 active READMS /WRITMS files and 20 
READDR/WRITDR files. 

Call from FORTRAN; 



CALL OPENMS (dn, index, length, it [,ierr] ) 
CALL OPENDR {dn, index, length, it[ , ierr] ) 



dn Type INTEGER variable, expression, or constant. The name 

of the dataset as a Hollerith constant or the unit number 
of the dataset (for example, dn~7 corresponds to dataset 
FT07) . 

index Type INTEGER array. The name of the array in the use^s 
program that is going to contain the master index to the 
records of the dataset. This array must be changed only by 
the random access dataset I/O routines. 
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length Type INTEGER variable, expression, or constant. The length 
of the index array. The length of index depends upon the 
number of records on or to be written on the dataset using 
the master index and the type of master index. The 
length must be at least 2*nrec if it*l or nveo if 
it=0. nrec is the number of records in or to be 
written to the dataset using the master index. 

it Type INTEGER variable, expression, or constant flag 

indicating the type of master index, 

it-0 Records synchronously referenced with a number 

between 1 and length* 
it=l Records synchronously referenced with an 

alphanumeric name of eight or fewer characters, 
it- 2 Records asynchronously referenced with a number 

between 1 and length, 
it-3 Records asynchronously referenced with an 

alphanumeric name of eight or fewer characters* 

For a named index, odd' numbered elements of the index array 
contain the record name, and even numbered elements of the 
index array contain the pointers to the location of the 
record within the dataset. For a numbered index, a given 
index array element contains the pointers to the location 
of the corresponding record within the dataset. 

ierr Type INTEGER variable. Error control and code. If ierr 

is supplied on the call to OPENMS/OPENDR, ierr returns 
any error codes to the user. If ierr is not supplied, an 
error aborts the job. 

If the user sets ierr>0 on input to OPENMS/OPENDR, error 
messages are not placed in the logfile. Otherwise, an 
error code is returned, and the error message is added to 
the job's logfile. OPENMS/OPENDR writes an open message to 
the logfile whether the value of ierr selects log 
messages or not. 

On output from OPENMS/OPENDR: 
ieri^O No errors detected 

<0 Error detected, ierr contains one of the 
error codes in table 5-7. 
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Table 5-7. Error codes for record-addressable, random 
access dataset I/O routines 



Code 


Routines 




Number 


Affected 


Description 


~1 


OPENDR 


■ ----- i i i ii 
The dataset name or unit number is 




OPENMS 


illegal. 




WRITDR 






WRITMS 






READDR 






READMS 






STINDR 






STINDX 






CLOSDR 






CLOSMS 






CHECKDR 






CHECKMS 






WAITDR 






WAITMS 






ASYNCDR 






ASYNCMS 






SYNCDR 






SYNCMS 




-2 


OPENDR 


The user-supplied index length is less than 






or 




OPENMS 


equal to 0. 


-3 


OPENDR 


The number of datasets has exceeded memory 




OPENMS 


or size availability. 


-4 


OPENDR 


The dataset index length read from the 




OPENMS 


dataset is greater than the user-supplied 






index length (nonfatal message) . 


-5 


OPENDR 


The user-supplied index length is greater 




OPENMS 


than the index length read from dataset 






(nonfatal message) . 
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Table 5-7. Error codes for record-addressable , random 
access dataset I/O routines (continued) 



Code 
Number 


Routines 
Affected 


Description 


-6 


WRITMS 
READMS 
FINDMS 


The user-supplied named index is illegal. 


-7 


WRITMS 
READMS 


The named record index array is full. 


-8 


WRITMS 
READMS 
FINDMS 


The index number is greater than the 
maximum on the dataset. 


-9 


WRITMS 
READMS 


Rewrite record exceeds the original. 


-10 


READMS 
FINDMS 


The named record was not found in the 
index array. 


-11 


OPENMS 


The index word address read from the 
dataset is less than or equal to 0. 


-12 


OPENMS 


The index lenoth read from the dataspt is 
less than 0. 


-13 


OPENMS 


The dataset has a checksum error. 


-14 


OPENMS 


OPENMS already has opened the dataset. 


-15 


WRITMS 
WRITDR 
READMS 
CLOSMS 
STINDR 
STINDX 


OPENMS/OPENDR was not called on this 
dataset. 
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Table 5-7* Error codes for record-addressable, random 
access dataset I/O routines (continued) 



Code 
Number 


Routines 
Affected 


Description 


-15 


FINDMS 

CHECKMS 

CHECKDR 

WAITMS 

WAITDR 

ASYNCMS 

ASYNCDR 

SYNCMS 

SYNCDR 

WAITDR 

WAITMS 


OPENMS/OPENDR was not called on this 
dataset. 


-16 


STINDR 
STINDX 


A STINDX/STINDR call cannot change the 
index type. 


-17 


WRITMS 
WRITDR 
READMS 
FINDMS 


The index entry is less than or equal to 0 
in the user*s index array. 


-18 


WRITMS 
WRITDR 
READMS 
FINDMS 


The user-supplied word count is less than 
or equal to 0. 


-19 


WRITMS 
WRITDR 
READMS 
FINDMS 


The user-supplied index number is less 
than or equal to 0. 


-20 


OPENMS 
OPENDR 


Dataset created by WRITDR/WRITMS 
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WRITMS/WRITDR writes data from user memory to a record in a random access 
dataset on disk and updates the current index . 

Call from FORTRAN: 



CALL JfiRITMS (dn, ubuff,n,irec r rrflag,s I, ierr] ) 
CALL WRl?m(dn r ubuff,n, iree r ri>flag,s[ r ierv] ) 



dn Type INTEGER variable, expression/ or constant. The name 

of the dataset as a Hollerith constant or the unit number 
of the dataset (that is, dn=l corresponds to dataset 
FTO 7) . 

ubuff Type determined by user. The location of the first word in 
the user's program to be written to the record. 

n Type INTEGER variable, expression, or constant. The number 

of words to be written to the record, n contiguous words 
from memory, beginning at ubuff, are written to the 
dataset record. Since COS unblocked dataset I/O is in 
multiples of 512 words, it is recommended that n be a 
multiple of 512 words when speed is of importance. 
However, the random access dataset I/O routines support a 
record length other than multiples of 512 words. WRITDR 
rounds n up to the next multiple of 512 words, if 
necessary. 

ireo Type INTEGER variable, expression, or constant. The record 

number or record name of the record to be written. A 
record name is limited to a maximum of eight characters. 
For a numbered index, iree must be between 1 and the 
length of the index declared in the OPENMS/OPENDR call. 
For a named index , iveo is any 64-bit entity the user 
specifies. 

vvftag Type INTEGER variable, expression, or constant. A flag 
indicating record rewrite control, vrflag can be one of 
the following codes. 

0 Write the record at BOD. 

1 If the record already exists and the new record 
length is less than or equal to the old record length, 
rewrite the record over the old record, if the new 
record length is greater than the old, abort the job 
step or return the error code in ierr. If the record 
does not exist, the job aborts or the error code is 
returned in iew. 
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-1 If the record exists and its new length does not exceed 
the old length, write the record over the old record. 
Otherwise, write the record at EOD. 

s Type INTEGER variable, expression, or constant. A 
sub-index flag.^ 

ievv Type INTEGER variable. Error control and code. If ievv 

is supplied on the call to WRHMS/WRITDR, ievv returns any 
error codes to the user. If ievv>0, no error messages are 
put into the logfile. Otherwise, an error code is returned 
and the message is added to the job's logfile. 

On output from WRITMS/WRITDR : 
ievv=0 No errors detected 

<0 Error detected, ievv contains one of the 
error codes in table 5-7. 



READMS/READDR reads a record from a random access dataset to a contiguous 
memory area in the user's program. 



/////////////////////////////////////////////////////// 

WARNING 

If you are using READDR in asynchronous mode and the 
record size is not a multiple of 512 words, user data 
can be overwritten and not restored. With the SYNCDR 
routine, the dataset can be switched to read 
synchronously, causing data to be copied out and 
restored after the read has completed. 

/////////////////////////////////////////////////////// 



Call from FORTRAN: 



CALL READMS {dn,ubuff,n ,ivee [ ,ievr] ) 
CALL READDR {dn, ubuff r n, iveo [, ievv] ) 



t Deferred implementation 
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dn Type INTEGER variable, expression, or constant. The name 

of the dataset as a Hollerith constant or the unit number 
of the dataset (for example, unit-7 corresponds to 
dataset FT07) . 

ubuff Type specified by user* The location in the user's program 
where the first word of the record is placed. 

n Type INTEGER variable, expression, or constant. The number 

of words to be read, n words are read from the random 
access record iveo and placed contiguously in memory, 
beginning at ubuff. If necessary, READDR rounds n up 
to the next multiple of 512 words. If the file is in 
synchronous mode, the data is saved and restored after the 
read. 

-ivec Type INTEGER variable, expression, or constant. The record 

number or record name of the record to be read. A record 
name is limited to a maximum of eight characters. For a 
numbered index, ireo must be between 1 and the length of 
the index declared in the 0PENMS /OPENDR call. For a named 
index, ireo is any 64-bit entity the user specifies. 

ier*p Type INTEGER variable. Error control and code. If ierv 

is supplied on the call to READMS /READDR , ierv returns 
any error codes to the user. If ieri»0, no error 
messages are put into the logfile. Otherwise, an error 
code is returned and the message is added to the job's 
logfile. 

On output from READMS/READDR : 
ierr^O No errors detected 

<Q Error detected, ierr contains one of the 
error codes in table 5-7. 



CLOSMS/CLOSDR writes the master index specified in OPENMS/ OPENDR from the 
user's program area to the random access dataset and then closes the 
dataset. Statistics are collected on the activity of the random access 
dataset and written in a readable format to dataset $STATS. (See table 
5*8). The statistics can be written to $0UT by using the following 
control statements or their equivalent after the random access dataset 
has been closed by CLOSMS/CLOSDR . 

REWIND , DN=$STATS , 
COPYF , I =$STATS , 0*$0UT . 
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Call from FORTRAN: 



CALL CLOSMS (dn [ r ierr] ) 
CALL CLOSDR (dn [ , i err] ) 



dn 



Type INTEGER variable, expression, or constant. The name of 
the dataset as a Hollerith constant or the unit number of the 
dataset (that is, dn-1 corresponds to dataset FT07) . 



ierr Type INTEGER variable* Error control and code. If ierr is 

supplied on the call to CLOSMS/CLOSDR, ierr returns any 
error codes to the user. If ierr>0, no error messages are 
put into the logfile. Otherwise, an error code is returned 
and the message is added to the job f s logfile. 



CLOSMS/CLOSDR writes a message to $LOG upon closing the dataset whether or 
not the user has requested error messages to be written to the logfile. 

On output from CLOSMS/CLOSDR: 
ierr-Q No errors detected 

<0 Error detected, ierr contains one of the 
error codes in table 5-7, 



******************************************************* 



CAUTION 

If a job step terminates without closing the random 
access dataset with CLOSMS/CLOSDR , the dataset 
integrity is questionable. 

******************************************************* 



Table 5-8, CLOSMS statistics 



Message 


Description 


TOTAL ACCESSES = 
READS = 
WRITES = 


Number of accesses 
Number of reads 
Number of writes 
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Table 5-8. CLOSMS statistics (continued) 



Message 


Description 


SEQUENTIAL READS *= 


Number of sequential reads 


SEQUENTIAL WRITES - 


Number of sequential writes 


REWRITES IN PLACE = 


Number of rewrites in place 


WRITES TO EOI = 


Number of writes to EOI 


TOTAL WORDS MOVED = 


Number of words moved 


MINIMUM RECORD = 


Minimum record size 


MAXIMUM RECORD = 


Maximum record size 


TOTAL ACCESS TIME = 


Total access time 


AVERAGE ACCESS TIME - 


Average access time 



STINDX/STINDR allows an index other than the master index to be used as 
the current index by creating a sub-index. STINDX/STINDR reduces the 
amount of memory needed by a dataset containing a large number of 
records* It also maintains a dataset containing records logically 
related to each other. Records in the dataset, rather than records in 
the master index area, hold secondary pointers to records in the dataset. 

STINDX/STINDR allows more than one index to manipulate the dataset* 
Generally, STINDX/STINDR toggles the index between the master index 
(maintained by OPENMS/OPENDR and CLOSMS/CLOSDR) and a sub-index (supplied 
and maintained by the user) . 

The user is responsible for maintaining and updating sub-index records 
stored in the dataset. Records in the dataset can be accessed and 
changed only by the current index. 

After a STINDX/STINDR call, subsequent calls to READMS/READDR and 
WRITMS/WRITDR use and alter the current index array specified in the 
STINDX/STINDR call. The user saves the sub- index by calling 
STINDX/STINDR with the master index array, then writes the sub-index 
array to the dataset using WRITMS/WRITDR, Retrieving the sub-index is 
performed by calling READMS/READDR on the record containing the sub-index 
information. STINDX/STINDR thus allows logically infinite index trees 
into the dataset and reduces the amount of memory needed for a random 
access dataset containing many records. 
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CAUTION 

When generating a new sub-index (for example, building 
a database) , the array or memory area used for the 
sub-index must be set to 0. If the sub-index storage 
is not set to 0 r unpredictable results occur* 

*********************** ****** ************************** 



Call from FORTRAN: 



CALL STINDX (dn, index, length, it [,ierr] ) 
CALL STiNDR(<i>7, index, length, it[,ierr] ) 



dn Type integer variable, expression, or constant. The name of 

the dataset corresponding to COS conventions as a Hollerith 
constant or the unit number of the file (that is, unit-1 
corresponds to dataset FT07) . 

index Type integer array. The user-supplied array used for the 
sub-index or new current index. If index is a sub-index, 
it must be a storage area that does not overlap the area 
used in OPENMS/OPENDR to store the master index. 

length Type integer variable, expression, or constant. The length 
of the index array. The length of index depends upon the 
number of records on or to be written on the dataset using 
the master index and the type of master index. If it=l, 
length must be at least twice the number of records on or 
to be written to the dataset using index* If it-0, 
length must be at least the number of records on or to be 
written to the dataset using index. 

it Type integer variable, expression, or constant. A flag to 

indicate the type of index. When it=*Q, the records are 
referenced with a number between 1 and length. When 
ti=l, the records are referenced with an alphanumeric name 
of eight or fewer characters. For a named index, 
odd-numbered elements of the index array contain the record 
name, and even-numbered elements of the index array contain 
the pointers to the location of the record within the 
dataset. For a numbered index, a given index array element 
contains the pointers to the location of the corresponding 
record within the dataset. 

The index type defined by STINDX/STINDR must be the same as 
that used by OPENMS/OPENDR. 
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ierr Type integer variable. Error control and code. If ierr 

is supplied on the call to STINDX/STINDR, ierr returns any 
error codes to the user. If ierr>0, no error messages are 
put into the logfile. Otherwise f an error code is returned 
and the message is added to the job's logfile. 

On output from STINDX/STINDR: 
ierr^O No errors detected 

<0 Error detected, ierr contains one of the 
error codes in table 5-7 . 



FINDMS asynchronously reads the desired record into the data buffers used 
by the random access dataset routines for the specified dataset. The 
next READMS or WRI1MS call waits for the read to complete and transfers 
data appropriately. 

Call from FORTRAN: 



CALL FINDMS (dn, n, iree[ f ierr\ ) 



dn Type integer variable, expression, or constant. The name 

of the dataset as a Hollerith constant or the unit number 
of the dataset (that is, dn-7 corresponds to dataset 
FT07) . 

n Type integer variable, expression, or constant. The 

number of words to be read as in READMS or WRITMS. 

iree Type integer variable, expression, or constant. The 

record name or number as in READMS or WRITMS to be read 
into the data buffers. 

ierr Type integer variable. Error control and code. If 

ierr is supplied on the call to FINDMS, ierr returns 
any error codes to the user. If ierr>0, no error 
messages are put into the logfile. Otherwise, an error 
code is returned and the message is added to the job's 
logfile. 

On output from FINDMS: 
ierr=Q No errors detected 

<0 Error detected, ierr contains one of the 
error codes in table 5-7. 
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AS YNCMS /AS YNCDR sets the I/O mode for the random access routines to be 
asynchronous. Therefore , input/output operations can be initiated and 
subsequent execution can proceed simultaneously with the actual data 
transfer* With READMS, asynchronous reads should be done with the FINDMS 
routine . 

Call from FORTRAN: 



Call ASYWCMS(dnl,ierr] ) 
Call ASYNCDR(c?n[,i<?rr]) 



dn Type integer variable , expression, or constant. The name 

of the dataset as a Hollerith constant or the unit number 
of the dataset (for example, dn=7 corresponds to dataset 
FT07) . 

ierr Type integer variable. Error control and code. If ierr 

is supplied on the call to AS YNCMS/AS YNCDR r ierr returns 
any error codes to the user. If ierr>0, no error 
messages are put into the logfile. Otherwise, an error 
code is returned and the message is added to the job's 
logfile. 

On output from AS YNCMS/AS YNCDR: 
ierr=0 No errors detected 

<0 Error detected, ierr contains one of the 
error codes in table 5-7. 



S YNCMS /S YNCDR sets the I/O mode for the random access routines to be 
synchronous. All input/output operations wait for completion. 

Call from FORTRAN: 



CALL SYNCMS(<2n ) 
CALL SY1*CDR(dn[ t ierr]) 



dn Type integer variable, expression, or constant. The name 

of the dataset as a Hollerith constant or the unit number 
of the dataset (for example, dn-1 corresponds to dataset 
FT07) . 
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ierr Type integer variable. Error control and code* If ierr 

is supplied on the call to S YNCMS/SYNCDR , ierr returns 
any error codes to the user. If ierr>0, no error 
messages are put into the logfile. Otherwise, an error 
code is returned and the message is added to the job's 
logfile. 

On output from S YNCMS/SYNCDR : 
ierr=0 No errors detected 

<0 Error detected, ierr contains one of the 
error codes in table 5-7. 



CHECKMS/CHECKDR checks the status of an asynchronous random access input 
or output operation. A status flag is returned to the user, indicating 
whether the specified dataset is active. 

Call from FORTRAN: 



CALL CHECKMS (dn , istat [ , ierr] ) 
CALL CHECKDR (dn , istat I , ierr) ) 



dn Type integer variable, expression, or constant. The name 

of the dataset as a Hollerith constant or the unit number 
of the dataset. (For example, dn=7 corresponds to 
dataset FT07.) 

istat Type integer variable. Dataset I/O Activity flag. 

istat^O No I/O activity on the specified dataset. 
istat=\ I/O activity on the specified dataset 

ierr Type integer variable. Error control and code* If ierr 

is supplied on the call to CHECKMS/CHECKDR, ierr returns 
any error codes to the user. If ierr>0, no error 
messages are put into the logfile. Otherwise, an error 
code is returned and the message is added to the job's 
logfile. 

On output from CHECKMS/CHECKDR: 
ierr=0 No error detected 

<0 Error detected, ierr contains on of the 
error codes in table 5-7. 
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WAITMS/WAITDR waits for the completion of an active asynchronous input or 
output operation. A status flag is returned to the user, indicating 
whether the I/O on the specified dataset was completed without error* 

Call from FORTRAN: 



CALL WAITMS (dn , is t at [,ierr]) 
CALL WAITDR (dn , istat [ , ier r] ) 



dn Type integer variable, expression, or constant. The name 

of the dataset as a Hollerith constant or the unit number 
of the dataset. (For example, dn-7 corresponds to 
dataset FT07.) 

istat Type integer variable. Dataset error flag. 

i8tat=0 No error occurred during the asynchronous 

I/O operation* 
istat-l Error occurred during the asynchronous I/O 
operation. 

ierr Type integer variable. Error control and code. If ierr 

is supplied on the call to WAITMS/WAITDR, ierr returns 
any error codes to the user. If ierr>0, no error 
messages are put into the logfile. Otherwise, an error 
code is returned and the message is added to the job's 
logfile. 

On output from WAITOS/WAITDR: 
ierr=0 No errors detected 

<0 Error detected, ierr contains one of the 
error codes in table 5-7. 

The following examples show some of the features and uses of random 
access dataset routines. 



SR-0014 



5-98 



I 



Example 1: 



In the program SORT/ a sequence of records is read in and then printed 
out as a sorted sequence of records. 

1 PROGRAM SORT 

2 INTEGER I ARRAY (512) 

3 INTEGER INDEX (512), KEYS (100) 

4 CALL OPENMS ( 'SORT' , INDEX, 255,1) 

5 N=50 

C READ IN RANDOM ACCESS RECORDS FROM UNIT "SORT" 

6 DO 21 1=1, N 

7 READ(5,1000) (I ARRAY (J) ,J=1,512) 

8 NAME= I ARRAY ( 1 ) 

9 KEYS(I)*IARRAY(1) 

10 CALL WRITMS ('SORT' , I ARRAY, 51 2, NAME, 0) 

11 21 CONTINUE 

C SORT KEYS ALPHABETICALLY IN ASCENDING ORDER USING EXCHANGE SORT 

12 DO 23 1=1, N-l 

13 MIN=I 

14 J=I+1 

15 DO 22 K=J,N 

16 IF (KEY (K) . LT.KEYS (MIN) ) MIN=K 

17 22 CONTINUE 

18 IB=KEYS(I) 

1 9 KEYS ( I ) «KE YS (MIN ) 

20 KEYS (MIN) «IB 

21 23 CONTINUE 

C WRITE OUT RANDOM ACCESS RECORDS IN ASCENDING 

C ALPHABETICAL ORDER 

22 DO 24 1=1, N 

23 NAME=KE YS ( I ) 

24 CALL READMS ( ' SORT ' , IARRAY, 512 , NAME) 

25 WRITE(6,5120) ( IARRAY ( J) ,J=1, 512) 

26 24 CONTINUE 

27 1000 FORMAT (" ") 

28 5120 FORMAT (IX," ") 

29 CALL CLOSMS ('SORT') 

30 STOP 

31 END 



In this example, the random access dataset is initialized as shown in 
line 4. Lines 6 through 11 show that from unit 5 a record is read into 
array IARRAY and then written as a record to the random access dataset 
SORT. The first word of each record is assumed to contain an 8-character 
name to be used as the name of the record. 

Lines 12 through 21 show that the names of the records are sorted in the 
array KEYS. Lines 22 through 26 show that the records are read in and 
then printed out in alphabetical order. 
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Example 2: 



The programs INITIAL and UPDATE show how the random access dataset might 
be updated without the usual search and positioning of a sequential 
access dataset. 



Program INITIAL: 



1 PROGRAM INITIAL 

2 INTEGER IARRAY(512) 

3 INTEGER INDEX (512) 
C 

C OPEN RANDOM ACCESS DATASET 

C THIS INITIALIZES THE RECORD KEY "INDEX" 

C 

4 CALL OPENMS ( 'MASTER* , INDEX, 101,1) 
C 

C READ IN RECORDS FROM UNIT 6 AND 
C WRITE THEM TO THE DATASET "MASTER" 
C 

5 DO 10 1=1,50 

6 READ(6,600) (IARRAY(J) ,J=1,512) 

7 NAME=IARRAY ( 1 ) 

8 CALL WRITMS ( 'MASTER 1 ,IARRAY, 512, NAME, 0,0) 

9 10 CONTINUE 
C 

C CLOSE "MASTER" AND SAVE RECORDS FOR UPDATING 
C 

10 CALL CLOSMS ('MASTER') 

11 600 FORMAT (IX, ' ' ) 

12 STOP 

13 END 

Program UPDATE: 

1 PROGRAM UPDATE 

2 INTEGER INEWRCD(512) 

3 INTEGER INDX (512) 
C 

C OPEN RANDOM ACCESS DATASET CREATED IN THE 

C PREVIOUS PROGRAM "INITIAL" 

C 

C INDX WILL BE WRITTEN OVER THE OLD RECORD KEY 
C 

4 CALL OPENMS ( 'MASTER' , INDX, 101,1) 
C 

C READ IN NUMBER OF RECORDS TO BE UPDATED 
C 

5 READ (6,610) N 
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c 

C READ IN NEW RECORDS FROM UNIT 6 AND 

C WRITE THEM IN PLACE OF THE OLD RECORD THAT HAS 

C THAT NAME 

C 

6 DO 10 1=1, N 

7 READ<6,600) (INEWRCD(J) ,J*1,512) 

8 NAME= INEWRCD ( 1 ) 

9 CALL WRITMS ( 'MASTER 1 , INEWRCD, 512, NAME, 1, 0) 

10 10 CONTINUE 
C 

C CLOSE "MASTER" AND SAVE NEWLY UPDATED RECORDS 

C FOR FURTHER UPDATING 

C 

11 CALL CLOSMS ( "MASTER") 

12 600 FORMAT (IX, " ") 

13 610 FORMAT (IX," ") 

14 STOP 

15 END 



In this example, program INITIAL creates a random access dataset on unit 
MASTER; then program UPDATE replaces particular records of this dataset 
without changing the remainder of the records. 

Line 10 shows that the call to CLOSMS at the end of INITIAL caused the 
contents of INDEX to be written to the random access dataset. 

Line 4 shows that the call to OPENMS at the beginning of UPDATE has 
caused the record key of the random access dataset to be written to 
INDX. The random access dataset and INDX are the same now as the random 
access dataset and INDEX at the end of INITIAL. 

Lines 6 through 10 show that certain records are replaced. 



Example 3: 

The program SNDYMS is an example of the use of the secondary index 
capability, using STINDX. In this example, dummy information is written 
to the random access dataset. 



1 PROGRAM SNDYMS 

2 IMPLICIT INTEGER (A-Y) 

3 DIMENSION PINDEX(20) , SINDEX(30) ,ZBUFFR(50) 

4 DATA PLEN,SLEN r RLEN /20,30,50/ 
C OPEN THE DATASET. 

5 CALL OPENMS ( 1 ,P INDEX , PLEN , 0 , ERR) 
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6 IF (ERR.NE.O) THEN 

7 PRINT* , ' Error on OPENMS, err=*,ERR 

8 STOP 1 

9 ENDIF 

C LOOP OVER THE 20 PRIMARY INDICES. EACH TIME 
C A SECONDARY INDEX IS FULL, WRITE THE 
C SECONDARY INDEX ARRAY TO THE DATASET. 

10 DO 40 K=1,PLEN 

C ZERO ODT THE SECONDARY INDEX ARRAY. 

11 DO 10 I«1,SLEN 

12 10 SINDEX(I)=0 

C CALL STINDX TO CHANGE INDEX TO S INDEX. 

13 CALL STINDX (1 ,SINDEX,SLEN, 0,ERR) 

14 IF (ERR.NE.O) THEN 

15 PRINT*,* Error on STINDX, err=',ERR 

16 STOP 2 

17 ENDIF 

C WRITE SLEN RECORDS. 
16 DO 30 J=1,SLEN 

C GENERATE A RECORD LENGTH BETWEEN 1 AND RLEN. 

19 TRLEN=MAX0 ( IFIX {RANF (0) *FLOAT (RLEN) ) , 1) 

C FILL THE "DATA" ARRAY WITH RANDOM FLOATING POINT NUMBERS. 

20 DO 20 1=1 , TRLEN 

21 20 2BUFFR(I)=(J+SIN(FLOAT(I)))**(1.+RANF(0) ) 

22 CALL WRITMS { 1 , ZBUFFR, TRLEN , J, -1 , DUMMY, ERR) 

23 IF (ERR.NE.O) THEN 

24 PRINT* , 1 Error on WRITMS, err=*,ERR 

25 STOP 3 

26 ENDIF 

27 30 CONTINUE 

C "TOGGLE" THE INDEX BACK TO THE MASTER AND 
C WRITE THE SECONDARY INDEX TO THE DATASET. 

28 CALL STINDX ( 1,P INDEX, PLEN, 0) 

C NOTE THE ABOVE STINDX CALL DOES NOT USE THE 
C OPTIONAL ERROR PARAMETER, AND WILL ABORT 
C IF STINDX DETECTS AN ERROR. 

29 CALL WRITMS ( 1 , S INDEX , SLEN , K , -1 , DUMMY , ERR) 

30 IF (ERR.NE.O) THEN 

31 PRINT*,* Error on STINDX, err=',ERR 

32 STOP 4 

33 ENDIF 

34 40 CONTINUE 

C CLOSE THE DATASET. 

35 CALL CLOSMS (1,ERR) 

36 IF (ERR.NE.O) THEN 

37 PRINT*,' Error on CLOSMS, err- ' ,ERR 

38 STOP 5 

39 ENDIF 

40 STOP 'Normal* 

41 END 
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WORD-ADDRESSABLE , RANDOM ACCESS DATASET I/O ROUTINES 

A word-addressable, random access dataset consists of an adjustable 
number of contiguous words. Any word or contiguous sequence of words is 
accessible from a word-addressable, random access dataset using the 
associated word-addressable, random access I/O routines. These dataset s 
and their I/O routines are similar to the record-addressable, random 
access datasets and their I/O routines. The FORTRAN -callable 
word-addressable, random access I/O routines are: WOPEN, WCLOSE, PUTWA, 
APUTWA, GETWA and SEEK. WOPEN opens a dataset and specifies it as a 
word-addressable, random access dataset that can be accessed or changed 
with the word-addressable I/O routines. The WOPEN call is optional. If 
a user call to GETWA or PUTWA is executed first, the dataset is opened 
for the user with the default number of blocks (16) and istats turned 
on. 

Call from FORTRAN: 



CALL WOPEN (dn,bloaks, istats [,ierr] ) 



dn Type integer variable, expression, or constant. The name of 

the dataset as a Hollerith constant or the unit number of 
the dataset (for example, 7 corresponds to FT07) . 

blocks Type integer variable, expression, or constant. The maximum 
number of 512-word blocks that the word-addressable package 
can use for a buffer. 

istats Type integer variable, expression, or constant. If istats 
is nonzero, then statistics about the changes and accesses 
to the dataset dn are collected. (See table 5-9 for 
information about the statistics that are collected.) These 
statistics are written to dataset $STATS and can be written 
to $OUT by using the following control statements or their 
equivalent after the dataset has been closed by WCLOSE. 

REWIND , DN-$STATS • 
COPYD , I»$STATS , 0=$OUT . 

ievr Type integer variable. Error control and code. If ierr 

is supplied on the call to WOPEN, ierr returns any error 
codes to the user. If ierr is not supplied, an error 
aborts the job. 

On output from WOPEN: 

ierr^O No errors detected 

<0 Error detected, ierr contains one of the 
error codes in table 5-10. 
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Table 5-9. WOPEN statistics 





1 Desc riot ion 


BUFFERS USED = 


Number of 512-word buffers used by this dataset 


TOTAL ACCESSES = 


Number of accesses. This is the sum of the GETWA 
and PTJTWA calls. 


GETS = 


Number of times the user calls GETWA 


PUTS = 


Number of times the user calls PUTWA 


FINDS = 


Number of times the user calls SEEK 


HITS = 


Number of times word addresses desired were 
resident in memory 


11 -L k»J h-7 J_j 
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resident in memory 


PARTIAL HITS = 


Number of times that some but not all of the word 


DISK READS - 


Number of ohvsical disk reads don** 


DISK WRITES = 


Number of times a physical disk was written to 


BUFFER FLUSHES « 


Number of times buffers were flushed 


WORDS READ = 


Number of words moved from buffers to user 


WORDS WRITTEN = 


Number of words moved from user to buffers 


TOTAL WORDS = 


TOTAL WORDS* Sum of WORDS READ and WORDS WRITTEN 


TOTAL ACCESS TIME = 


Real time spent in disk transfers 


AVER ACCESS TIME = 


TOTAL ACCESS TIME divided by the sum of DISK 
READS and DISK WRITES 


EOD BLOCK NUMBER = 


Number of the last block of the dataset 


DISK WORDS READ = 


Count of number of words moved from disk to 
buffers 


DISK WDS WRITTEN = 


Count of number of words moved from buffers to 
disk 
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Table 5-9. WOPEN statistics (continued) 



Message 


Descr iot ion 


TOTAL DISK XFERS = 
BUFFER BONUS % * 


Sum Of DISK WORDS BEAD and DISK WDS WRITTEN 

TOTAL WORDS divided by value TOTAL DISK XFERS 
multiplied by 100 



PUTWA writes a number of words from memory to a word-addressable, random 
access dataset. 

APUTWA asynchronously writes a number of words from memory to a 
word-addressable , random-access dataset. 

Call from FORTRAN: 



CALL PUTWA (dn , source , addr, count [ 9 ierr\ ) 
CALL APUTWA {dn, source, addr, count [ , ierr] ) 



dn Type integer variable , expression, or constant* The name 

of the dataset as a Hollerith constant or the unit number 
of the dataset (for example, 7 corresponds to FT07) . 

source Variable or array of any type. The location of the first 
word in the user's program to be written to the dataset, 

addr Type integer variable, expression, or constant. The word 

location of the dataset that is to receive the first word 
from the user's program. addr=l indicates beginning of 
file. 

count Type integer variable, expression, or constant. The number 
of words from source to be written. 

ierr Type integer variable. Error control and code. If ierr 

is supplied on the call to PUTWA, ierr returns any error 
codes to the user. If ierr is not supplied, an error 
causes the job to abort. 



On output from PUTWA/APUTWA: 
ierr~0 No errors detected 

<0 Error detected, ierr contains one of the 
error codes in table 5-10. 
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GETWA synchronously reads a number of words from the word-addressable, 
random access dataset into the user's memory. The SEEK routine performs 
asynchronous word-addressable input . 

Call from FORTRAN: 



CALL GETWA (dn ,re8ult, addr, count [ ,ierr] ) 



dn Type integer variable, expression, or constant. The name 

of the dataset as a Hollerith constant or the unit number 
of the dataset (for example, 7 corresponds to FT07) ♦ 

result Variable or array of any type. The location in the 

user's program where the first word is placed. 

Type integer variable, expression, or constant. The word 
location of the dataset from which the first word is 
transferred. 

Type integer variable, expression, or constant. The 
number of words from result written into the user's 
memory from the dataset. 

Type integer variable. Error control and code. If 
ierr is supplied on the call to GETWA, ierr returns 
any error codes to the user. If ierr is not supplied, 
an error causes the job to abort* 

On output from GETWA: 
ierr-0 No errors detected 

<0 Error detected, ierr contains one of the 
error codes in table 5-10. 



Table 5-10. Error codes for word-addressable, random 
access dataset I/O routines 



Code 


Routines 




Number 


Affected 


Description 


-1 


WOPEN 


Illegal unit number 




APUTWA 






PUTWA 






GETWA 






WCLOSE 






SEER 





addr 



count 



ierr 
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Table 5-10. Error codes for word-addressable , random 
access dataset I/O routines (continued) 



Code 
Number 


Routines 
Affected 


Descript ion 


-2 


WOPEN 

APUTWA 

PUTWA 

GETWA 

SEEK 


Number of datasets has exceeded memory or 
size availability. 


-3 


GETWA 
SEEK 


User attempt to read past end of data 


-4 


APUTWA 
PUTWA 
GETWA 
SEEK 


User-supplied word address less than or 
equal to 0 


-5 


APUTWA 

PUTWA 
GETWA 
SEEK 


User-requested word count greater than 
maximum 


-6 


WOPEN 

APUTWA 

PUTWA 

GETWA 

WCLOSE 

SEEK 


Illegal dataset name 


-7 


APUTWA 
PUTWA 
GETWA 
SEEK 


User word count less than or equal to 0 
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WCLOSE finalizes the additions and changes to the word-addressable 
dataset and closes the dataset. 

Call from FORTRAN: 



CALL WCLOSE (dn [ , ierr] ) 



dn Type integer variable, expression, or constant. The name 

of the dataset as a Hollerith constant or the unit number 
of the dataset (for example, 7 corresponds to FT07) . 

ierr Type integer variable, expression, or constant. Error 

control and code. If ierr is supplied on the call to 
WCLOSE, ierr returns any error codes to the user. If 
ierr is not supplied, an error aborts the job. 

On output from WCLOSE: 

ierr=Q No errors detected 

<0 Error detected, ierr contains one of the 
error codes in table 5-10. 



SEEK asynchronously reads data into specified dataset buffers. The SEEK 
and GETWA calls are used together. The SEEK call reads the data 
asynchronously; the GETWA call waits for I/O to complete and then 
transfers the data. The SEEK call moves the last write operation pages 
from memory to disk, loading the user-requested word addresses to the 
front of the I/O buffers. The user can load as much data as fits into 
the dataset buffers. Subsequent GETWA and PUTWA calls that reference 
word addresses in the same range do not cause any disk I/O. 

Call from FORTRAN: 



CALL SEEK {dn ,addr, count [ ,ierr] ) 



dn Type integer variable, expression, or constant. The name of 

the dataset as a Hollerith constant or the unit number of 
the dataset (for example, 7 corresponds to FT07) . 

addr Type integer variable, expression, or constant. The word 

address of the next read. 

count Type integer variable, expression, or constant. The number 
of words of the next read. 
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iew Type integer variable, expression, or constant. Error 

control and code. Error control and code. If iew is 
supplied on the call to SEEK, iew returns any error codes 
to the user. If iew is not supplied, an error aborts the 
job. 

On output from SEEK: 

ierr*Q No errors detected 

<0 Error detected, iew contains one of the 
error codes in table 5-1 0. 



Example : 

Assume a user wants to use a routine that reads word addresses 1,000,000 
to 1,051,200. A dataset could be opened with 101 blocks of buffer space, 
and CALL SEEK (dn, 1000000, 51200, iew) can be used before calling the 
routine. Subsequent GETWA or PUTWA calls with word addresses in the 
range of 1,000,000 to 1,051,200 do not trigger any disk I/O. 



WORD-ADDRESSABLE I/O AND DATASET CONTROL ROUTINES 

Word-addressable and I/O dataset control routines are normally called by 
FORTRAN I/O routines and communicate with the system through Exchange 
Processor requests. 

OPENWA opens a word-addressable dataset. 
Call from FORTRAN: 

CALL OPENWA (dn , index, ieoi , iaddv, blocks, idsp) 



dn Dataset name or unit number 

index On exit, contains relative index into the Dataset 

Parameter Table (DSP) area where this dataset name goes 

ieoi On exit, contains the number of disk blocks 

iaddv On exit, contains the address of the buffer assigned to 

this dataset 

blocks Number of blocks of memory to request from the system 

idsp Address of DSP assigned 
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Subsequent OPEN or CLOSE 
changes , etc., can cause 



NOTE 

statements, field length 
the DSP address to change. 



CLOSEWA closes a word-addressable dataset. 
Call from FORTRAN: 

CALL CLOSEWA (index) 

index Offset in Dataset Parameter Table (DSP) area 

READWA reads words from a word-addressable dataset. 
Call from FORTRAN: 

CALL READWA (index , buffer, address ,ont,rel) 

index Offset in Dataset Parameter Table (DSP) area 

buffer Buffer to receive data 

address Word address on disk to read 

ont Number of words to read 

rel Recall flag. If 0, waits for completion. 

WRITEWA writes words from a word-addressable dataset. 
Call from FORTRAN: 

CALL WRITEWA (index , buffer, address ,ent, rat) 

index Offset into Dataset Parameter Table (DSP) area 

buffer Buffer to receive data 
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address Word address on disk to write 

ont Number of words to write 

vet Recall flag. If 0, waits for completion* 

WDSETB sets buffer address to current value. 
Call from FORTRAN: 

CALL WDSETB (dn , index , iaddr) 

dn Dataset name or unit number 

index Offset into Dataset Parameter Table (DSP) area 

iaddr Value to get buffer address 

WDSET sets dataset names for word-addressable datasets. 
Call from FORTRAN : 

CALL WDSET {dn 9 idn ) 

dn Dataset name or unit number 

idn On exit f returns dataset name or 0 if error 
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DATASET MANAGEMENT 
SUBPROGRAMS 



INTRODUCTION 



Dataset management subprograms provide the user with the means of 
managing permanent datasets, staging datasets, creating datasets, 
changing dataset attributes, and releasing datasets. These routines are 
grouped into control statement type, dataset search type, and I/O type. 



CONTROL STATEMENT TYPE SUBPROGRAMS 

The control statement type subprogram resembles job control language 
(JCL) control statements in name and purpose* However, a subprogram can 
be called from within a FORTRAN or CAL program while JCL control 
statements cannot. See the CRAY-OS Version 1 Reference Manual, 
publication SR-0011, for a description of the parameters. 

Following is an example of a FORTRAN call to a control statement type 
subprogram. 

EXAMPLE 1 EXAMPL 1 L 
IDC= , PR , L 

CALL ASSIGN (ir£<2, f DN f L r EXAMPL, 'U'L, 'MR'L, v DC v L r IDC) 

ivte is an integer variable that contains a status code upon return. 
The status code is 0 if the call was successful. 

This type of subprogram requires call-by-address subroutine linkage with 
the following calling sequence. 



CALL SUBROUTINE NAME {stat r key} 



stat Returned status code 

key Keyword/value combinations in one of the following formats: 
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1 keyword* l#, 1 value* L or % keywovd*l* 



NOTE 

See the CRAY-OS Version 1 Reference Manual, publication 
SR-0011 for control statements and their keywords. 



PERMANENT DATASET MANAGEMENT (PDM) ROUTINES 

Permanent dataset management routines access the COS Permanent Dataset 
Manager and return the status of the operation in parameter 1. The value 
is equal to 0 if no error condition exists , and not equal to 0 if an 
error condition does exist . 



ACCESS associates a permanent dataset with the job* 



ADJUST expands or contracts a permanent dataset. 



DELETE removes a saved dataset. The dataset remains available for the 
life of the job. 



MODIFY changes permanent dataset characteristics. 



SAVE makes a dataset permanent and enters the dataset v s identification 
and location into the Dataset Catalog. 

PERMIT specifies user access mode to a user permanent dataset by other 
users. 



DATASET STAGING ROUTINES 

Dataset staging routines stage files to or from a front-end processor or 
to the Cray input queue. The job aborts if an error occurs. 
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ACQUIRE obtains a front-end resident dataset, stages it to the Cray 
mainframe, and makes it permanent and accessible to the job making the 
request. 



DISPOSE directs a dataset to the specified front-end processor. 

FETCH brings a front-end resident dataset to the Cray mainframe and makes 
the dataset local* 



SUBMIT places a job dataset into the Cray input queue. 



DEFINITION AND CONTROL ROUTINES 

Definition and control routines allow changing of dataset attributes and 
creation and release of datasets. They return the status of the 
operation in parameter 1. The value of parameter 1 is 0 if no error 
condition exists and is not equal to 0 if an error condition exists* 



ASSIGN opens dataset for reading and writing and assigns characteristics 
to it. 



RELEASE closes a dataset, releases I/O buffer space, and renders it 
unavailable to the job. 



SDACCESS allows a program to access datasets in the System Directory. 
This function has no control statement. 

Call from FORTRAN: 



CALL SDACCESS {istat,dn) 



istat An integer variable to receive the completion status (0 or 
1). 

If 0 r the dataset is a system dataset and has been accessed. 
If 1, the dataset is not a system dataset and has not been 
accessed ♦ 

dn Name of the system dataset to be accessed 
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Example : 



This example is in a general format. 

IF NOT (IFDNT(NAME)) THEN 
BEGIN 

CALL SDACCESS (STATUS, NAME); 
IF STATUS < > 0 THEN 
BEGIN 

OUTPUT ( 1 ***DATASET NOT AVAILABLE 1 ; 
BLANKFILL (NAME) : A8) ; 
CALL ABORT; 
END 
END 



DATASET SEARCH TYPE SUBPROGRAMS 

$SDSP searches Dataset Parameter Table (DSP) for a dataset name and 
returns DSP address. 

Call from CAL: 



CALLV $SDSP 



Entry: 

(SI) Dataset name or alias (ASCII, left- justified, zero-filled) 
Exit: 

(SI) Dataset name or alias 

(AO) Return code, positive if found; negative if not found. 

(Al) Dataset Parameter Table (DSP) address 



$SLFT searches Logical File Table (LFT) for dataset name and returns LFT 
address. 

Call from CAL: 

CALLV $SLFT 
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Entry: 
(SI) 
Exit: 



Dataset name (ASCII, left-justified, zero-filled) 



(SI) 
(AO) 
(A2) 



Dataset name 

Return code, positive if found; negative if not found. 
LFT address 



ADDLFT and $ALF add a name to the Logical File Table (LFT) • 



Call from FORTRAN: 



CALL ADDLFT {dn r dsp} 



dn 



Name to add to Logical File Table (LFT) 



dsp 



Dataset Parameter Table (DSP) address for name 



Call from CAL: 



CALLV $ALF 



Entry: 

(SI) Name to add to Logical File Table (LFT) 
(Al) Dataset Parameter Table (DSP) address for name 
Exit : 

No arguments returned 



$DSNDSP searches Logical File Table in the user's I/O area for dataset 
name and returns Dataset Parameter Table (DSP) address* 

Call from CAL: 



CALLV $DSNDSP 



Entry: 

(SI) Dataset name (ASCII, left- justified, zero- or blank-filled) 
Exit: 

(SI) Dataset name 

(Al) Dataset Parameter Table (DSP) address (0 if not found) 
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GETDSP and $GTDSP% search for a Dataset Parameter Table (DSP) address. 
If none is found, a DSP is created* 



Call from CAL: 



CALLV $GTDSP% 



Entry: 

(Al) Address of dataset name or unit number 
Exit: 

(Al) Address of Dataset Parameter Table (DSP) 

(51) Negative DSP offset relative to base of DSPs if system area 
DSP; DSP address if user area DSP, 

(52) Dataset name (ASCII, left-justified, blank-filled) 

Call from FORTRAN: 



CALL GETDSV(unit,dsp,nd8p,dn) 



unit 


Dataset name or unit number 




dap 


Dataset Parameter Table (DSP) 




ndsp 


Negative DSP offset relative to base 


address of DSPs 


dn 


Dataset name (ASCII, left- justified, 


blank-filled) 



IFDNT determines if a dataset has been accessed. 
Call from FORTRAN: 

stat-IFDNT {dn) 

stab .TRUE, if dataset was accessed or opened; otherwise, .FALSE. 

dn Dataset name (ASCII, left- justified, zero-filled) 



NOTE 

IFDNT must be declared LOGICAL in the calling program. 
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NUMBLKS returns current size of dataset in 512-word blocks « 
Call from FORTRAN: 



va!=NUMBLKS(cfa) 



vat Number of blocks returned as integer value. If number of 

blocks cannot be determined, a negative function value is 
returned. 

dn Dataset name or unit number 



DATASET INPUT/OUTPUT SUBPROGRAMS 

Before the 1.09 release, these subprograms were used for input/output 
control. Although they are still usable, use of the FORTRAN unblocked 
I/O subprograms (see section 5) is recommended. 

OPEN opens a random, unblocked dataset. 
Call from FORTRAN: 



CALL OVEtt(dst r dn,ds,dstat) 



dst Dataset Parameter Table (DSP) , Open Dataset Name Table 

(ODN) , and Dataset Definition List (DDL) array (dataset 
tables normally residing in the high-address end of the 
user field) 

dn Dataset name or unit number 

ds Dataset size 

d&tat Dataset status 

On exit, dataset size and status returned to locations specified in 
entry. See RDIN note below for description of status. 
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CLOSE terminates processing of a random, unblocked dataset. 
Call from FORTRAN: 

CALL CLOSE (dst) 

dst Dataset Parameter Table (DSP) , Open Dataset Name Table 

(ODN) , and Dataset Definition List (DDL) array (dataset 
tables normally residing in the high-address end of the 
user field) 

On exit, no arguments returned 

RDIN reads one buffer of data from a random, unblocked dataset. 
Call from FORTRAN: 

CALL RDIN (dst ,abuf r sbuf ,bnum,stat ) 

dst Dataset Parameter Table (DSP) , Open Dataset Name Table 

(ODN) , and Dataset Definition List (DDL) array (dataset 
tables normally residing in the high-address end of the 
user field) 

abuf Buffer area 

sbuf Buffer size 

bnum Block number 

stat Return status is stored 

On exit, dataset status returned in locations specified in entry 



NOTE 

Status consists of Dataset Parameter Table (DSP) error 
flags, right-justified. The return status is 0 if no 
error occurred. 
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TABLES 



PDD is the table of permanent dataset definitions* 

PDD is created and managed by some of the dataset management subprograms, 
so the user generally has no need to be concerned with it. For a 
detailed description of the table, see the CRAY-OS Version 1 Reference 
Manual, publication SR-0011. 
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SPECIAL PURPOSE SUBPROGRAMS 



INTRODUCTION 

Special purpose subprograms are grouped into the following categories: 

• Debug aid routines 

• Table management routines 

• Stack management routines 

• Heap management routines 

• Job control routines 

• Floating-point interrupt routines 

• Bidirectional memory transfer routines 

• Time and date routines 

• Timestamp routines 

• Control statement processing routines 

• Job control language symbol routines 

• SKOL run-time support routines 

• Error processing routines 

• Byte and bit manipulation routines 

• Miscellaneous special-purpose routines 

DEBUG AID ROUTINES 

Debug aid routines consist of 

• Flow trace routines 

• Traceback routines 
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# Dump routines 

# Exchange Package processing routines 
m Array bounds checking routines 

FLOW TRACE ROUTINES 

Flow trace routines process the CFT flow trace option (ON=F) . (See the 
FORTRAN (CFT) Reference Manual, CRI publication SR-0009, for details on 
flow tracing.) Calls to these routines are automatically inserted into 
code by the CFT compiler. A CAL call to a flow trace routine must be 
preceded by an ENTER macro or its equivalent. Flow trace routines are 
called by address. 

FLOWENTR processes entry to a subroutine. 
Call from CAL and FORTRAN: 

CALL FLOWENTR 



FLOWEXIT processes RETURN execution. 
Call from CAL and FORTRAN : 

CALL FLOWEXIT 



FLOWSTOP processes a STOP statement. 
Call from CAL and FORTRAN: 

CALL FLOWSTOP 



GETNAMEQ returns the ASCII, left-justified, space-filled name of the 
routine that called FLOWENTR or FLOWEXIT. 
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Call from FORTRAN: 



CALL GETNAMEQ (arg) 
Entry: 

arg Address of output 
Exit: 

Caller name stored in address pointed to by arg 

GETREGS returns register usage statistics for FLOWENTR. 
Call from FORTRAN: 

CALL GETREGS (arg) 

Entry: 

arg Address of output array 
Exit: 

Statistics stored in array 

SETPLIMQ initiates detailed tracing of every call and return. 
Call from FORTRAN: 

CALL SETPLIMQ (lines) 

lines Number of trace lines printed 

ARGPLIMQ initiates listing of argument values for every call and return. 
This subprogram can be called only once in the user program. 

Call from FORTRAN: 

CALL ARGPLIMQ ( list) 
list List of argument values for every call and return 
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FLOWLIM sets a limit on the number of subroutine calls that can be 
traced. A summary is printed when the limit is reached. 

Call from FORTRAN: 



CALL FUMm(limit) 



limit Limit of the number of subroutine calls that can be traced 



TRACEBACK ROUTINES 

$TRBK and TRBK print a list of all subroutines active in the current 
calling sequence from the currently active subprogram. It also 
identifies the address of the reference. The user can specify a unit to 
receive the list. If no unit is specified, the list is printed to the 
user logfile. 

Call from FORTRAN: 



CALL TRBK[ (CLT*g) ] 



avg Address of dataset name or unit number 



TRBKLVL aids the traceback mechanism by returning information for the 
current level of the calling sequence. 

Call from CAL: 



CALLV TRBKLVL % 



Entry: 

(A2) Traceback table address of the current level (the B and T 

register save area) 
(A3) Argument list address of the current level's caller 
Exit: 

(A2) Traceback table address of the current level* s caller; 0 if 

current level is a main level routine. 
(A3) Argument list address of the current level's caller; 0 if 

current level is a main level routine. 
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(SI) 



(S2) 
(S3) 
(S4) 
(S5) 

(S6) 



Status: <0 if error 

=0 if no error 

>0 if no error and current level is main level 
Name of current level (ASCII, left-justified, blank-filled) 
Parcel address from where call to current level was made 
Parcel address of current level's entry point 
Line sequence number corresponding to call address; 0 if 
none. 

Number of arguments and registers passed to current level. 



Call from FORTRAN: 



CALL TRBKLVL (trbkt ab,argli at , status, name, calladr, entpnt,seqnum 9 nwnavg) 



tvbktab Current level's traceback table address. On exit, current 
level's caller's traceback table address. Zero if current 
level is a main level routine. 

arglist Current level's argument list address. On exit, current 
level's caller's argument list address. Zero if current 
level is a main level routine. 

status <0 if error 

=0 if no error 

>0 if no error and current level is main level 

name Current level's name (ASCII, left-justified, blank-filled) 

oaVladv Parcel address from where call to current level was made 

entpnt Parcel address of current level's entry point 

seqnwn Line sequence number corresponding to call address (a zero 
indicates none) 

numarg Number of arguments or registers passed to current level 



DUMP ROUTINES 

Dump routines produce a memory image and are called by address. 



$PDUMP and PDUMP dump memory to $OUT and return control to calling program. 
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Call from FORTRAN: 

CALL vdump (fwd, Iwd, type) 

fwd First word to be dumped 

Iwd Last word to be dumped 

type Dump type code: 

0 or 3 Octal dump 

1 Floating-point dump 

2 Integer dump 

$DUMP and DUMP dump memory to $OUT and abort the job. 
Call from FORTRAN: 

CALL dump {f *wd,lwd, type) 

fwd First word to be dumped 

Iwd Last word to be dumped 

type Dump type code: 

0 or 3 Octal dump 

1 Floating-point dump 

2 Integer dump 



NOTE 

• If 4 is added to the dump type code, first word and 
last word addresses specified above are then 
addresses of addresses (indirect addressing) . 

• First word/last word/dump type address sets can be 
repeated up to 19 times. 



DUMP JOB creates an unblocked dataset containing the user job area image 
(including register states) . This data is suitable for input to the DUMP 
or DEBUG programs. 
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Oall from FORTRAN: 



CALL DUMP JOB (dn) 



dn FORTRAN unit number or Hollerith unit name. If no 

parameter is supplied, $DUMP is used by default* 



SNAP copies current register contents to $OUT. 
Call from FORTRAN : 



CALL SNAP (regs , control, form) 



regs Code indicating registers to be copied: 

1 B registers 

2 T registers 

3 B and T registers 

4 V registers 

5 B and V registers 

6 T and V registers 

7 B, T f and V registers 

control Control word (not currently used) 

form Code indicating format of dump. Dumps from registers S, 

and V are controlled by the following type codes: 

0 Octal 

1 Floating-point 

2 Decimal 

3 Hexadecimal 

Dumps from registers A and B are in octal format. 



SYMDEBUG and DEADBUG produce a symbolic dump. 
Call from FORTRAN: 



CALL SYMDEBUG (char) 
CALL DEADBUG 



char Character string (integer) 
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The character string consists of the keyword/parameter 
pairs listed with the DEBUG utility in the CRAY-OS 
Version 1 Reference Manual, publication SR-0011. The 
string must terminate with a period. 



CRAYDUMP prints a memory dump to a specified dataset. 



Call from FORTRAN: 



CALL CRAYDUMP (fwa, twa,dn) 



fwa 



First word to be dumped 



Iwa 



Last word to be dumped 



dn 



Name or unit number of the dataset to receive the dump 
output 



EXCHANGE PACKAGE PROCESSING ROUTINES 

Exchange processing switches execution from one program to another. An 
Exchange Package is a 16-word block of memory associated with a 
particular program* The Exchange Package processing routines include 
XPFMT, $FXP, FXP, and B20CT. 



XPFMT produces a printable image of an Exchange Package in a 
user-supplied buffer, A and S registers appear in the buffer in both 
octal and character form; in the character form, the contents of the 
register are copied unchanged to the printable buffer. The calling 
program is responsible for proper translation of non-printable 
characters. Parcel addresses have a lowercase a, b, c f or d suffixed to 
the memory address. 

The user can specify that the Exchange Package be formatted as a CRAY-1 
or CRAY X-MP Exchange Package, or can allow XPFMT to determine which 
format to use based on the values in the Exchange Package. Values within 
the Exchange Package determine the Exchange Package format. XPFMT 
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assumes the Exchange Package was produced by or for a CRAY X-MP computer 
if either the data base address or the data limit address is nonzero* 
Otherwise, it assumes the Exchange Package was produced by or for a 
CRAY-1 computer. 

Call from FORTRAN: 



call xpfmt (address , in , out ,mode ) 



address The nominal location of the Exchange Package to be printed 
as the starting Exchange Package address. This is not the 
address of the 16-word buffer containing the Exchange 
Package to be formatted* 

A 16-word integer array containing the binary 
representation of the Exchange Package 

An integer array, dimensioned (8,0:23) into which the 
character representation of the Exchange Package is 
stored. Line 0 is a ruler for debugging and is not usually 
printed (see figure 7-1) . 

The first word of each line is an address and need not 
always be printed. 

An integer word indicating the mode in which the Exchange 
Package is to be printed. f S'L forces the Exchange Package 
to be formatted as a CRAY-1 Exchange Package; 'X'L forces 
the Exchange Package to be formatted as a CRAY X-MP 
Exchange Package; 0 means that the subprogram is to use the 
Exchange Package value to deduce the machine type. 

Figure 7-1 is an example of a printout when the mode 
selected is 'X'L. 

FXP and $FXP format and write to the output dataset the contents of the 
Exchange Package, the contents of the vector mask (VM) , and the contents 
of the BO register. These routines complement the user reprieve 
processing code by formatting the supplied Exchange Package to an output 
dataset. 

Call from CAL: 



CALLV $FXP 



out 



mode 
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Entry; 

(Al) Address of output Dataset Parameter Area (DSP) 

(A7) Address of Exchange Package 

(S2) Vector mask (VM) to be formatted 

(A3) Contents of BOO to be formatted 
Exit: 

(Al) Output DSP address 

(A7) Exchange Package address 

Call from FORTRAN: 



CALL FXP(d8p,xp,vm,ret) 



dsp Output Dataset Parameter Area (DSP) address 

xp Exchange Package address 

vm Vector mask (VM) to be formatted 

ret Contents of BO to be formatted 



B20CT places the ASCII representation of the low-order n bits of a full 
Cray word into a specified character area. 

Call from FORTRAN: 



CALL B20CT(S r< 7,fe f V r n) 



8 First word of an array where the ASCII representation is to 

be placed 

J Byte offset within array s where the first character of 

the octal representation is to be placed, A value of 1 
indicates the destination begins with the first (leftmost) 
byte of the first word of 3. j must be greater than 0, 

k Number of characters used in the ASCII representation, k 

must be greater than 0. k is the size of the total area 
to be filled and it is blank-filled if necessary. 

v Value to be converted. The low-order n bits of word v 

are used to form the ASCII representation, v must be 
less than or equal to 2 63 -l. 
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n Number of low-order bits of y to convert to ASCII 

character representation (l<n<64) . If insufficient 
character space is available (3k<n) , the character region 
is filled with asterisks (*) • 

The k characters pointed to by j in array s are first set to blanks. 
The low-order n bits of v are then converted to octal ASCII, using 
leading zeros if necessary • The converted value (n/3 characters, rounded 
up) is right-justif ied into the blanked-out destination character region. 

? 

oooooooo P ooooooooa AO oooooooo aaa MODES FLAGS 

oooooooo IBA oooooooo Al oooooooo aaa OFF ON OFF ON 

oooooooo I LA oooooooo A2 oooooooo aaa MM MM PCI PCI 

oooooooo XA oooo VL ooo A3 oooooooo aaa I CM I CM MCU MCU 

oooooooo DBA oooooooo A4 oooooooo aaa IFP IFP FPE FPE 

oooooooo DLA oooooooo A5 oooooooo aaa IUM IUM ORE ORE 

oooooooo A6 oooooooo aaa IMM IMM PRE PRE 

oooooooo A7 oooooooo aaa SEI SEI ME ME 

BDM BDM 101 IOI 

oooooooo SO ooooooooooooooooooooooo aaaaaaaa FPS FPS EEX EEX 

oooooooo SI ooooooooooooooooooooooo aaaaaaaa WS WS NEX NEX 

oooooooo S2 ooooooooooooooooooooooo aaaaaaaa IOR IOR DL DL 

oooooooo S3 ooooooooooooooooooooooo aaaaaaaa ICP ICP 
oooooooo S4 ooooooooooooooooooooooo aaaaaaaa 
oooooooo S5 ooooooooooooooooooooooo aaaaaaaa 
oooooooo S6 ooooooooooooooooooooooo aaaaaaaa 
oooooooo S7 ooooooooooooooooooooooo aaaaaaaa 





PROCESSOR = o CLUSTER = o PS = o 
ERROR TYPE - aaaaaaaaaaaaaaaa VU = o 
CHIP SLCT *= oooooo BANK = oo 
READ MODE = aaaaaa SYNDROME = ooo 



a means alpha 
o means octal 

(T) Derived from address parameter 

(?) Character representation of A registers 

(J) Character representation of S registers 

(4) A mode or flag mnemonic appears in the ON or OFF column depending on 
the state of the mode or flag bit in the Exchange Package. 

Figure 7-1 • Exchange Package printout 
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ARRAY BOUNDS CHECKING ROUTINES 



$STOREF and $LOADP are generated by the compiler to perform run-time 
array bound checking. See the FORTRAN (CFT) Reference Manual, CRI 
publication SR-0009, for details on array bound checking. 



TABLE MANAGEMENT ROUTINES 

Table management routines perform the following functions. 

FORTRAN CAL Function 

TMINIT $INT Initializes managed tables 

TMATS $ATS Allocates space to a table 

TMADW $ADW Adds a word to a table 

TMSRC $MSC, $MSCO, Searches a table with or without masking 
$SRC 

TMPTS $PTS%, $ZTS% Presets memory with any given value (default 

is 0) 

TMMVE $MVE Moves memory 

TMMEM $MEM Requests additional memory 

TMAMU $AMV Returns table management operation statistics 

The routines in the FORTRAN column are FORTRAN callable and those in the 
CAL column are CAL callable. The Job Communication Block (JCB) field 
JCHLM defines the beginning address of the table area. 

The user must provide two control information tables with corresponding 
CAL ENTRY pseudo-ops : 

# Table Base Table (BTAB) 

• Table Length Table (LTAB) 
Their formats follow. 

BTAB 2/- , 14/ISP^ , 24/AL^ , 24/BASE^ 

ISP^ Normal interspace between table^ and 

table i+1 , 

AL£ Current allocated table length, and 

BASE£ First word address of table^. 
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LTAB 40/-,24/LEN£ 



LEN-£ Current length of table^ 

The last entry in each control information table (TEND) must be a dummy 
entry. The TEND entry has zeros in the AL and LEN fields . The ISP field 
in the TEND entry contains the minimum field length increment to be made 
for table space. If the Table Manager needs to expand the job f s field 
length, it does so by a minimum of ISP words. ISP is ignored for $MEM 
calls* 

The number of entries in a control information table must not exceed 64 , 
TEND included. (The FORTRAN callable versions of these routines use a 
default BTAB and LTAB definition from a common area in $ SYS LIB.) 

1MINIT initializes the table descriptor vector, BTAB, and zeros all 
elements of the table length vector, LTAB. The user must preset each 
element of BTAB to contain the desired interspace value for the 
corresponding table; for instance, SI in the example below determines the 
interspace value for table 1. Interspace values determine how many words 
are added to a table when more room is needed for that table or for any 
table with a lower number. 

TMINIT accepts a single parameter, n, in the prototype statements 
below, which determines the number of tables that can exist for the life 
of the calling program. 

After the call to TMINIT, BTAB should not be changed. The interspace 
values have been shifted 48 bits to the left, bits 16 through 39 contain 
the current size of each table, and the rightmost 24 bits contain the 
absolute address of each table's first word. LTAB is used only to pass 
new table lengths from the user to the Table Manager. 

INTEGER, BTAB (n) , LTAB(tt) 
DATA BTAB /sl,s2 , s3. . . , sn/ 



CALL TMINIT 

The FORTRAN programmer can use statements like the following to access 
each table. In this example, table i is accessed, 

EQUIVALENCE (BTAB(i) , PTRi) 
INTEGER PTRi, TABLE i (0:0) 
POINTER (PTRi, TABLE i) 



TABLEi (subscript) = ... 
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TM COMMON BLOCK 



The common block labeled TM is reserved for use by the Table Manager and 
must always contain 64 BTAB words and 64 LTAB words. 

COMMON /TM/ BTAB (64) , LTAB (64) 

Blank common can be used in the customary way, but the last entry in it 
should be for a 1 -dimensional array declared to contain just one word. 
The name of this array is then used to access the tables, beginning 
immediately after the end of blank common. 

COMMON // TABLES (1) 

The following statement function extracts the rightmost 24 bits from a 
BTAB word and changes that value from an absolute address to a relative 
address or offset within the table area. Thus the result of BASE (N) is 
an index into TABLES (1) pointing to the first word currently allocated to 
table N. 

BASE (N) = (BTAB (N) .AND. 77777777B) - LOC (TABLES (1) ) 



WRITE (6,101) TABN 

101 FORMAT ( f 0 Dump of table ',12,/) 

OFFSET = 0 

102 CONTINUE 

DO 103 I = 1, 4 

INTABLE = OFFSET . LT. LTAB (TABN) 
IF (INTABLE) THEN 

OCTAL (I) * TABLES (1 + BASE (TABN) + OFFSET) 

ALPHA (I) = TABLES (1 + BASE (TABN) + OFFSET) 
ELSE 

OCTAL (I) = 0 

ALPHA ( I ) = 1 1 
END IF 

OFFSET = OFFSET + 1 

103 CONTINUE 

WRITE (6,104) OFFSET- 4, OCTAL, ALPHA 
104 FORMAT (16, 2X, 4(022, IX) ,4A8) 

INTABLE = OFFSET .LT. LTAB (TABN) 
IF (INTABLE) GO TO 102 

WRITE (6,105) 
105 FORMAT (/) 

RETURN 
END 
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$INT initializes table pointers. Upon entry , the user must provide all 
table interspace values. The remaining BTAB and LTAB fields are set by 
$INT. LTAB array is zeroed. Memory to be used for the managed tables is 
zeroed. 

Call from CAL: 



CALLV $INT 



TMINIT initializes managed tables. Upon entry, the BTAB array contains 
the desired table expansion increments. Upon exit, the BTAB array is 
initialized, the LTAB array is zeroed, and the memory to be used for the 
managed tables is zeroed. 

$MEM requests memory. 
Call from CAL: 

CALLV $MEM 

Entry: 

(Al) Length of memory field requested 
Exit: 

No arguments returned. Memory is extended by requested amount* 

TMMEM requests memory. Upon exit, memory is extended by the requested 
amount. No value is returned. 

Call from FORTRAN: 

CALL TMMEM (mem) 

mem Length of memory requested 

$ATS allocates table space. 
Call from CAL: 

CALLV $ATS 
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Entry; 



(Al) 
(SI) 



Table pointer 
Increment 



Exit: 



(A2) 
(A3) 



Pointer to expanded portion of table 
Address of expanded portion of table 



TMATS allocates table space. 



Call from FORTRAN: 



index^TMATS (number, in ere) 



index 



Index of change 



number 



Table number 



inare 



Table increment 



$ADW adds a word to a table. 
Call from CAL: 



CALLV $ADW 



Entry: 

(Al) Table pointer 

(SI) Entry for table 

Exit: 

(A2) Index of word 

(A3) Address of word 



TMADW adds a word to a table. 
Call from FORTRAN: 



index^TMRDVi (number, entry) 



index Index of word 
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number Table number 
entry Entry for table 

$MSC searches table with mask to locate a specific field within an entry. 
Call from CAL: 



CALLV $MSC 



Entry : 

(51) Search word 

(52) Field being searched for within entry 
(Al) Table number 

(A2) Number of words per table entry 
Exit: 

(AO) Address of match, if found; 0 if match not found. 

(A3) Address of match, if found 



TMMSC searches table with mask to locate a specific field within an entry. 
Call from FORTRAN: 



index^TmSC (tabnum f ma8k , sword, mdord) 



index Table index of match, if found; -1 if not found* 

tabnum Table number 

mask Field being searched for within entry 

sword Search word 

rword Number of words per entry group 



$MSCO searches table with mask to locate a specific field within an entry 
and an offset. 



Call from CAL: 



CALLV $MSCO 
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Dcaivii wora 




Field hf> i na c;#a^ rr*H ^rl ■Fnr wi fhin anfru 


f Al> 


Table number 


<A2) 


Number of words per table entry 


(A4) 


Word offset within entry to be searched 


Exit: 




(AO) 


Address of match, if found; 0 if match not found. 


(A3) 


Address of match, if found 



$SRC searches table for a specific value. 
Call from CAL: 



CALLV $SRC 



Entry : 




(SI) 


Search word 


(Al) 


Table number 


(A2) 


Number of words per table entry 


Exit: 




(AO) 


Address of match, if found; 0 if match not found. 


(A2) 


Table index of match, if found 


(A3) 


Address of match, if found 


<A4) 


Ordinal of entry, or next ordinal if no match. First entry 




ordinal is 0. 



TMSRC searches table with optional mask to locate a specific field within 
an entry and an offset. 

Call from FORTRAN: 



index^TMSRC (tabnum,arg , nwovd , offset 9 mask) 



index Table index of match, if a match is found; -1 if not found. 

tabnwn Table number to search 

avg Search argument or key 

nwovd Number of words per entry 

offset Offset into entry group 

mask Field being searched for within entry 
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TMVSC searches vector table for the search argument. 
Call from FORTRAN: 



index-TMVSC (tabnum ,arg ,m)ord) 



index 



Table index match, if found; 



1 if not found. 



tabnum 



Table number 



arg 



Search argument 



nwovd 



Number of words per entry group 



$AMU returns total allotted table space. 
Call from CAL: 

CALLV $AMU 

Entry: 

No arguments required 
Exit: 

(A2) Allocated length of tables 
(A3) Number of table entries 

TMAMU reports TMGR statistics. 
Call from FORTRAN: 

CALL TMAMU (len, tabnum t tabmov, tabmar,m>ord) 

ten Allocated length of table 

tabnum Number of tables used 

tabmov Number of table moves 

tabmar Maximum amount of memory used throughout Table Manager 

rtwovd Number of words moved 
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$PTS* presets table space. 
Call from CAL: 



CALLV $PTS% 



Entry: 

(Al) Base address of space 

(A2) Length to be preset or zeroed 

(SI) Preset 
Exit: 

(VO) Preset vector 

$ZTS% zeros table space. 
Call from CAL: 



CALLV $ZTS% 



Entry: 

(Al) Base address of space 
(A2) Length to be preset or zeroed 
Exit: 

(VO) Zero vector 



TMPTS presets table space. 
Call from FORTRAN: 



CALL TMPTS ( start ,len r pre s et ) 



start Starting address 
Zen Length to preset 

preset Preset value 



$MVE moves memory words to table. 
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Call from CAL: 



CALLV $MVE 
Entry : 

(Al) Address from where words are to be moved 

(A2) Address where words are to be moved 

(A3) Number of words to be moved 

TMMVE moves words. 
Call from FORTRAN: 

CALL TMMVE {from, to, count) 

from Address from where words are to be moved 

to Address where words are to be moved 

count Number of words to be moved 



STACK MANAGEMENT ROUTINES 

Stack management routines are called automatically by CPT compiler code 
or, if in stack mode, by the CAL EXIT and ENTER macros. 

A stack consists of a stack header plus one or more discontiguous 
segments. A stack segment includes memory for use as a stack followed by 
control words. Segment control words provide an overflow area and 
linkage to a discontiguous segment* Each discontiguous portion of the 
available space is linked through a control word to the next block of 
available space. The control word also contains the size of a given 
block . 

A stack header control word exists at the base of each stack. 



Format : 





0 


8 


16 


24 


32 


40 


48 


56 


63 


0 






GROW 




1 




ASEG 






1 






HWM 




1 




SIZE 
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SHGROW 



0 



0-31 



The number of times the stack has grown 



SHASEG 



31*63 Si2e of additional increments to the 

stack • Zero means overflow is a fatal 
error. 



SHHWM 
SHS1ZE 



1 
1 



0*31 The largest size of the stack so far, 

32-63 Current size of the stack; includes 

usable stack space for all stack 
segments 



Stack segment control words exist at the top of each stack segment. 



Format : 



0 8 16 24 32 40 48 56 63 



0 

• 
• 


PAD AREA 




* 

127 






128 


SIZE | 


BASE 


129 


/////////////////////////////////I 


PSEG 


130 


/////////////////////////////////I 


TCPT 



Field Word Bits Description 

PAD AREA 0-127 0-63 Area indicating that B/T register 

save can always occur before a stack 
overflow check is made* In a segment 
that has overflowed to a 
discontiguous segment, this area 
contains the traceback packet used in 
returning from the underflow routine. 



SSSIZE 128 0-31 Size of stack segment. Size includes 

the length of the stack header but 
does not include the length of stack 
segment control words* 
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Field Word Bits 

SSBASE 129 31-63 



Description 



Offset to stack base relative to the 
absolute top of stack. 



SSPSEG 



130 



32-63 



Offset to previous top of stack. If 
PSEG=0, this is an initial stack 
segment . 



SSTCPT 



131 



32-63 



Pointer to task common address block 
($TASKCQM) . 



Stack management routines perform the following functions. 



Routine 



Function 



$STKOFEN 
$STKCR 



Manages stack overflow 
Creates initial stack segment 
Manages stack underflow 
Releases a topmost stack segment 
Releases all stack segments 



$STKUFCK 
$STKUFEX 
$STKDE% 



$STKOFEN is called if stack overflow is detected during allocation of 
contiguous static space onto a stack at subprogram entry. Information 
from the JCB, the stack header, and the B register stack pointers 
determines how much additional space, if any, to allocate to the stack. 

The current stack segment is enlarged if possible. Otherwise, a 
discontiguous segment is created. In the latter case, the discontiguous 
segment is released from the stack on exit from the routine that caused 
the overflow condition. 

This routine creates a stack for the root task the first time overflow 
occurs. In all cases, it updates the B register stack pointers. 

Call from CAL: 



CALLV $STK0FEN 



No arguments required. 



$STKCR creates an initial stack segment and the stack header. 



SR-0014 7-23 I 



Call from CAL: 



CALLV tfSTKCR 



Entry: 
(SI) 
(S2) 



Initial size of stack 

Size of increments to this stack; zero implies stack 
overflow is a fatal error. 



Exit: 
(Al) 



Address of first available word 

(First word address + length of header) 

Size of stack (does not include the length of control words) 



(A2) 



3STKUFCK determines whether an exit sequence has produced stack 
underflow. This routine releases the topmost segment if underflow has 
occurred. 

Call Prom CAL: 



CALLV $STKUPCK 



No arguments required, 

$STKUFEX releases the topmost stack segment. The call to this routine 
occurs on exit from the routines that caused the stack to overflow to a 
discontiguous segment. 

Call from CAL: 



CALLV $STKUFEX 
No arguments required. 

$STKDE% releases all segments of the indicated stack to the available 
space. 

Call from CAL: 

CALLV $STKDE% 



No arguments required. 
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HEAP MANAGER ROUTINES 



Heap manager routines provide dynamic storage allocation by managing a 
block of memory within a user's job area, the heap. Each job has its own 
heap. The functions of the heap manager routines are allocating a block 
of memory, returning a block of memory to the heap's list of available 
space, and changing the length of a block of memory. Heap manager 
routines also move a heap block to a new location if there is no room to 
extend it, return part of the heap to the operating system, check the 
integrity of the heap, and report information about the heap* See the 
CRAY-OS Version 1 Reference Manual, publication SR-G011, for the location 
of the heap and parameters on the LDR control statement that affect the 
heap. 

The heap manager consists of the following routines. 



FORTRAN 

HPALLOC 

HPDEALLC 

HPNEWLEN 

HPCLMOVE 

IHPLEN 
HPSHRINK 

HPCHECK 
IHPSTAT 
HPDUMP 



GAL 

ALLOC% 

DEALLC% 

NEWLEN% 

CLMOVE% 

HPLEN% 
SHRINK% 

HCHECK% 
HPSTAT% 
HPDUMP% 



Function 

Allocate a block of memory from the heap 

Return a block of memory to the heap 

Change the length of a heap block 

Change the length of a heap block and move 
the block if it cannot be extended in place 

Return the length of a heap block 

Return memory from the heap to the operating 
system 

Check the integrity of the heap 

Return information about the heap 

Write information about the heap to a dataset 



The heap manager routines keep various statistics on the use of the 
heap. These include values used to tune heap parameters specified on the 
LDR control statement and information used in debugging. 



ALLOCATE ROUTINES 

Allocate routines search the linked list of available space for a block 
greater than or equal to the size requested. 



SR-0014 



7-25 



I 



The length of an allocated block can be greater than the requested length 
because blocks smaller than the managed memory epsilon specified on the 
LDR control statement are never left on the free space list. 

Error conditions checked in allocate routines: 

• Length is not an integer greater than zero (-1) 

• No more memory is available from the system (-2) (checked if the 
request cannot be satisfied from the available blocks on the heap) 

Call from CAL: 



CALLV ALLOC% 



Entry: 

(51) Size (number of words) of requested block 

(52) Abort flag: nonzero requests abort on error; zero requests 
an error code. 

Exit: 

(51) First word address of allocated block 

(52) Number of words requested (unchanged) 

(53) Error code: zero if no error was detected; otherwise, a 
negative integer code for the type of error. 

Call from FORTRAN: 



call HPALLOC (addr, length, errcode, abort) 



addv First word address of the allocated block (output) 

length Number of words of memory requested (input) 

erreode Error code: zero if no error was detected; otherwise, a 
negative integer code for the type of error (output) ♦ 

abort Abort code: nonzero requests abort on error; zero requests 
an error code (input) 
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DEALLOCATE ROUTINES 

Deallocate routines return a block to the list of available space. 
Error conditions checked in deallocate routines: 

* Address outside bounds of the heap (-3) 

• Block already free (-4) 

• Address not at beginning of block (-5) 

* Control word for next block overwritten (-7) 
Call from CAL: 



CALLV DEALLC% 



Entry: 

(SI) First word address of block being deallocated 
<S2) Nonzero requests abort on error; zero requests an error 
code. 

Exit: 

(SI) Error code: zero if no error was detected; otherwise, a 
negative integer code for the type of error. 

Call from FORTRAN: 



CALL HPDEALLC (addr 9 erroode , abort) 



addr First word address of the block to deallocate (input) 

erreode Error code: zero if no error was detected; otherwise, a 
negative integer code for the type of error (output) ♦ 

abort Abort code: nonzero requests abort on error; zero requests 
an error code (input). 



SET NEW LENGTH ROUTINES 

Set new length routines change the size of an allocated block. If the 
new length is less than the allocated length, the portion starting at 
ADDR+LENGTH is returned to the heap. If the new length is greater than 
the allocated length, the block is extended if it is followed by a free 
block* A status is returned, telling whether the change was successful. 
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The new length of the block can be greater than the requested length 
because blocks smaller than the managed memory epeilon specified on the 
LDR control statement are never left on the free space list. 



Error conditions checked in set new length routines: 

• Length not an integer greater than zero (-1) 

• Addresss outside the bounds of the heap (-3) 

• Block free (-4) 

• Address not at beginning of block (-5) 

• Control word for next block has been overwritten (-7) 
Call from CAL: 



CALLV NEWLEN% 



Entry: 

(51) Address of block to change 

(52) Requested new total length of block 

(53) Nonzero requests abort on error; zero requests an error 
code. 

Exit : 

(51) Address of block (unchanged) 

(52) Requested new total length (unchanged) 

(53) Status: zero if the change in length was successful; one 
if the block could not be extended in place; a negative 
integer for the type of error detected. 



Call from FORTRAN : 



CALL HPNEWLEN {addr, length, status f abort) 



addv First word address of the block to change (input) 

length Requested new total length of the block (input) 

status Status: zero if the change in length was successful; one 
if the block could not be extended in place; a negative 
integer for the type of error detected (output) . 

abort Abort code: nonzero requests abort on error; zero requests 
an error code (input) . 
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CHANGE LENGTH AND MOVE ROUTINES 



Change length and move routines extend a block if it is followed by a 
large enough free block or copy the contents of the existing block to a 
larger block and return a status code that the block has been moved. 
They can also reduce the size of a block if the new length is less than 
the old length. In this case, they have the same effect as the length 
change routines. 

The new length of the block can be greater than the requested length 
because blocks smaller than the managed memory epsilon specified on the 
LDR control statement are never left on the free space list. 

Error conditions checked in change length and move routines: 

• Length not an integer greater than zero (-1) 

• No more memory available from the system (-2) (checked if the 
block cannot be extended and the free space list does not include 
a large enough block) 

• Address outside the bounds of the heap (-3) 

• Block free (-4) 

• Address not at beginning of block (-5) 

• Control word for next block has been overwritten (-7) 
Call from CAL: 



CALLV CLMOVE% 



Entry : 



(SI) 
(S2) 
(S3) 



Address of block to change 
Requested new total length 

Abort code: nonzero requests abort on error; zero requests 
an error code. 



Exit: 
(SI) 



Address of changed block; this value can be different from 
the entry value. 

Requested new total length (unchanged) 

Status: zero if the block was extended in place; one if it 
was moved; a negative integer for the type of erjror 
detected. 



(S2) 
(S3) 
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Call from FORTRAN: 



CALL HPCLMOVE {addr, length, status, abort) 



addr On entry, first word address of the block to change; on 

exit, the new address of the block if it was moved 

length Requested new total length (input) 

status Status: zero if the block was extended in place; one if it 
was moved; a negative integer for the type of error 
detected (output) . 

abort Abort code: nonzero requests abort on error; zero requests 
an error code (input). 



HEAP BLOCK LENGTH ROUTINES 

Heap block length routines return the length of a heap block. The length 
of the block can be greater than the amount requested because of the 
managed memory epsilon* 

Error conditions checked in heap block length routines: 

• Address outside the bounds of the heap (-3) 

• Block free (-4) 

• Address not at beginning of block (-5) 

• Control word for next block has been overwritten (-7) 
Call from CAL: 



CALLV HPLEN% 



Entry : 
(SI) 
CS2) 

Exit: 
(SI) 
(S2) 
(S3) 



First word address of block 

Abort code: nonzero requests abort on error; zero requests 
an error code 

Number of words in the block 

First word address of block (copied from SI) 

Error code: zero if no error was detected; otherwise, a 

negative integer code for the type of error* 
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Call from FORTRAN: 



length^IHPLEN (addr, err code, abort) 



length Length of the block starting at addr (output) 

addr First-word-address of the block (input) 

erroode Error code: zero if no error was detected; otherwise, a 
negative integer code for the type of error (output) . 

abort Abort code: nonzero requests abort on error; zero requests 
an error code (input) . 



HEAP SHRINK ROUTINES 

Heap shrink routines return an unused portion of the heap to the 
operating system. This is done only if the blocks closest to HLM are 
free; no allocated blocks are moved. The minimum amount of memory to be 
returned is the managed memory increment specified on the LDR control 
statement. These routines are called only from the user program. 

Call from CAL: 

CALLV SHRINK% 

No arguments 

Call from FORTRAN: 

CALL HPSHRINK 

No arguments 



HEAP INTEGRITY CHECK ROUTINES 

Heap integrity check routines check the integrity of the heap. Each 
control word is examined to ensure that it has not been overwritten. 
Error conditions checked in heap integrity check routines: 

• Bad control word for allocated block (-5) 

• Bad control word for free block (-6) 



SR-0014 



7-31 



I 



Call from CAL: 



CALLV HCHECK% 



Exit : 

(SI) Error code: zero if no error was detected; otherwise 
negative integer code for the type of error. 

Call from FORTRAN: 



CALL HPCHECK (errcode) 



errcode Error code: zero if no error was detected; otherwise 
negative integer code for the type of error (output) . 



HEAP STATISTICS ROUTINES 

Heap statistics routines return statistics about the heap. 
Call from CAL; 



CALLV HPSTAT% 



Entry: 

(SI) Code for the information requested: 

1 Current heap length 

2 Largest size of the heap so far 

3 Smallest size of the heap so far 

4 Number of allocated blocks 

5 Number of times heap has grown 

6 Number of times heap has shrunk 

7 Last routine that changed the heap 

8 Caller of last routine that changed the heap 

9 First word address of heap area changed last 

10 Size of the largest free block 

11 Amount by which the heap can shrink 

12 Amount by which the heap can grow 

13 First word address of the heap 

14 Last word address of the heap 

Exit: 

(SI) Requested value 
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Call from FORTRAN: 



z>aXw<2-iHPSTAT (code) 



code Code for the type of information requested (see CAL entry 

point) 



value Requested information 



DUMP HEAP CONTROL WORD ROUTINES 

Dump heap control word routines dump the address and size of each block 
in the heap. Three types of dump are available: a dump of all heap 
blocks, a dump of free blocks that traces the links to the next block on 
the free list, and a dump of free blocks that traces the links to the 
previous block on the free list. The dump stops if an invalid value is 
found in a field needed to continue the dump. 

Call from CAL: 



CALLV HPDUMP* 



Entry: 

(51) Code for the type of dump requested: 

0 Print heap statistics 

1 Dump all heap blocks in storage order 

2 Dump free blocks; follow NEXT links. 

3 Dump free blocks; follow PREV links. 

(52) Dataset name; name of the dataset to which the dump is to 
be written. 

Call from FORTRAN: 



CALL hpdump (code, dsname) 



code Code for the type of dump requested (see CAL entry point) 

dename Name of the dataset to which the dump is to be written. 
dsname must be in left- justified, Hollerith form. 
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HEAP EXPANSION ROUTINE 

The heap expansion subroutine is used by the allocate and new length 
routines when there is not enough space in the heap to meet a request. 
The subroutine requests additional memory from the operating system, adds 
the new memory to the free space list in the heap, and adjusts the 
control words at the end of the heap. 



NOTE 

The heap expansion routine should not be called 
directly by a user program. 



Call from CAL: 



CALLV HPGROW% 



Entry: 

(SI) Number of words in pending allocate request 
Exit: 

{SI) Success flag; one if more memory was added to the heap, zero 
if the heap could not be expanded. 



HEAP MEMORY REQUEST ROUTINE 

The heap memory request routine requests more memory from the operating 
system to be added to the heap. 



NOTE 

The heap memory request routine should not be called 
directly by a user program. 



Call from CAL: 



CALLV HPMEM% 
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Entry: 

(SI) Number of additional words needed for the heap 
Exit; 

(SI) Number of additional words that can be added to the heap; 
zero if the heap could not be expanded* 



HEAP MERGE ROUTINE 

The heap merge routine is used by the heap shrink routine to coalesce 
free blocks before finding out how much the heap can shrink. It is also 
used by HPSTAT to determine how much the heap can shrink and the size of 
the largest free block in the heap. 



NOTE 

The heap merge routine should not be called directly by 
a user program. 



Call from CAL: 



CALLV HMERGE% 



Exit: 

(51) Last free block; zero if the last free block is allocated, 
or the address of the last heap block if it is free. 

(52) The size of the largest free block 



JOB CONTROL ROUTINES 

Job control routines perform functions relating to job step termination, 
either causing a termination or instructing the system how to handle a 
termination. Unless otherwise specified, these routines are called by 
address. No arguments are returned. 

ABORT requests abort with traceback and provides optional logfile 
message. The optional user-supplied logfile message is written to both 
user and system logfiles. The message is written in the same format in 
which it is sent. 
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Call from FORTRAN: 



CALL ABORT[ {tog} J 

log Logfile message 

END$ and $END terminate the job step and advance the job to the next job 
step* 

Call from FORTRAN: 
END 



$ENDRPV and ENDRPV continue normal exit processing after a reprievable 
request has been processed* This exit processing can be the result of 
normal termination or abort processing. 

Call from CAL: 

CALLV $ ENDRPV 
Call from FORTRAN: 

CALL ENDRPV 



ERREXIT requests abort. 
Call from FORTRAN: 

CALL ERREXIT 



EXIT provides exit for FORTRAN programs , writes the following message to 
the logfile, and advances the job to the next step* 

UT003 EXIT CALLED BY routine name 
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Call from FORTRAN: 



CALL EXIT 



NORERUN controls the monitoring of conditions causing the job to be 
flagged as not rerunnable* 

Call from FORTRAN: 



CALL NORERUN {param) 



param One argument is required. If argument is 0 # the system 
monitors for conditions causing the job to be flagged as 
not rerunnable. If nonzero, such conditions are not 
monitored. 



RERUN allows the user to declare the job rerunnable or not rerunnable. 
Call from FORTRAN: 



CALL RERUN (param) 



param One argument is required. If the argument is 0 r the job 
can be rerun. If the argument is nonzero, the job cannot 
be rerun. 



$SETRPV and SETRFV transfer control to the specified routine when a 
user-selected reprievable condition occurs. $SETRPV is called by value? 
SETRPV is called by address. See the Macros and Opdefs Reference Manual, 
CRI publication SR-0012, for details of the SETRFV parameter formats. 

Call from CAL: 



CALLV $SETRPV 



Entry : 

(Al) Reprieve code entry address 

(A2) Reprieve table address 

(SI) Mask 
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Call from FORTRAN : 



CALL SETKPV(rpvcode,rpvtab,mask) 



vpvoode 



Routine where control is transferred 



rpvtab 



A 40-word array reserved for system use 



mask 



User mask specifying reprievable conditions 



$STOP terminates the job step, advances the job to its next job step, and 
prints an optional user-supplied message to the logfile. The message is 
written in the same format in which it is sent. 

Call from CAL: 



CALL $STOP[, {log)] 



log Address of the logfile message 

$PAUSE suspends program execution . An installation parameter, I@PAUSE, 
determines whether $PAUSE or $STOP is to be executed. The default is 
program suspension. $PAUSE prints an optional user-supplied message to 
the logfile. The message is written in the same format in which it is 
sent. 

Call from CAL: 



FLOATING-POINT INTERRUPT ROUTINES 

Floating-point interrupt routines allow the user to test, set, and/or 
clear the Floating-point Interrupt Mode flag. Subroutine linkage is 
call-by-address . 



CALL $PAUSE[, Hog) ] 



log 



Address of optional logfile message 
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FLOATING-POINT INTERRUPT TEST 



The floating-point interrupt test routine determines whether interrupts 
are permitted or prohibited* 

SENSEFI determines the current interrupt mode. 
Call from FORTRAN: 

CALL SENSEFI (mode) 

mode Interrupt mode: 

If mode=l 9 permit interrupts. 
If mode^Ot prohibit interrupts. 



TEMPORARY FLOATING-POINT INTERRUPT CONTROL 

These routines are local to the current job step. The system restores 
the most recent mode setting at the start of the next job step. No 
arguments are required or returned. 

CLEARFI temporarily prohibits floating-point interrupts. 
Call from FORTRAN: 

CALL CLEARFI 



SETFI temporarily permits floating-point interrupts. 
Call from FORTRAN: 

CALL SETFI 



JOB FLOATING-POINT INTERRUPT CONTROL 

The results of routines are propagated through job steps. The system 
does not alter the mode setting unless another floating-point interrupt 
control subroutine is called or a MODE control statement is executed. No 
arguments are required or returned. 
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CLEARFIS prohibits floating-point interrupts for a job until they are 
enabled or the job terminates. 



Call from FORTRAN: 
CALL CLEARFIS 



SETFIS enables floating-point interrupts until they are explicitly 
disabled or the job terminates. 

Call from FORTRAN: 
CALL SETFIS 



BIDIRECTIONAL MEMORY TRANSFER ROUTINES 

Bidirectional memory transfer routines test, set, and/or clear the 
bidirectional Memory Transfer Mode flag. Subroutine linkage is 
call-by-address . 



NOTE 

These routines are only effective on the CRAY X-MP, 
which has hardware support for bidirectional memory 
transfer. 



BIDIRECTIONAL MEMORY TRANSFER TEST 

The bidirectional memory transfer test routine determines whether 
bidirectional memory transfer is enabled or disabled. 

SENSEBT determines the current memory transfer mode. 
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Call from FORTRAN; 



CALL SmSEBT{mode) 



mode Transfer mode: 

If mode=l 9 bidirectional memory transfer enabled 
If mode=0, bidirectional memory transfer disabled 



TEMPORARY BIDIRECTIONAL MEMORY TRANSFER CONTROL 

These routines are local to the current job step* The system restores 
the most recent mode setting at the start of the next job step. No 
arguments are required or returned, 

CLEARBT temporarily disables bidirectional memory transfers . 
Call from FORTRAN: 

CALL CLEARBT 



SETBT temporarily enables bidirectional memory transfers. 
Call from FORTRAN: 

CALL SETBT 



PERMANENT BIDIRECTIONAL MEMORY TRANSFER CONTROL 

The results of these routines are permanent and are propagated through 
job steps. The system does not alter the mode setting unless another 
bidirectional memory transfer control subroutine is called or a MODE 
control statement is executed. No arguments are required or returned. 
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CLEAKBTS permanently disables bidirectional memory transfers* 
Call from FORTRAN: 

CALL CLEARBTS 



SETBTS permanently enables bidirectional memory transfers. 
Call from FORTRAN: 

CALL SETBTS 



TIME AND DATE ROUTINES 

Time and date routines produce the time and/or date in specified forms. 
These routines can be called as FORTRAN functions or routines. All of 
the routines are called by address. 

CLOCK returns current system clock time in ASCII hhxmmiss format. 
Call from FORTRAN: 

tim^CLOCKO 
CALL CUDCK(time) 

time Time in hhzrmntss format (type integer) 

DATE returns today's date in mm/dd/yy format. 
Call from FORTRAN : 

date*DATE() 
CALL DATE (date) 

date Today's date in mn/dd/yy format (type integer) 
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JDATE returns today's Julian (ordinal) date in yyddd format , 
left-justified, blank-filled. 

Call from FORTRAN: 



date* JDATE () 
CALL JDATE {date) 



date Today's Julian date in yyddd format 



SECOOT) returns CPU time since start of job in floating-point seconds. 
Call from FORTRAN; 



seeond=SECOI&D( [result] ) 
CALL SECOND ( 3 econd) 



second Result (CPU time used by job since start of job in 

floating-point seconds) . Contents of SI stored at address 
of argument. 

result Same as above (optional for function call) 

TIMEF returns a value, in floating-point milliseconds, that is, the 
amount of wall-clock time passed since the initial call to TIMEF in the 
program. 

Call from FORTRAN: 



timef=HIMEF( [result] ) 
CALL TIMEF [timef) 



timef Wall-clock time passed since the initial call to TIMEF, in 
floating-point milliseconds. The initial call to TIMEF 
returns 0. 

result Same as timef 

TREMAIN returns CPU time remaining for job execution in floating-point 
seconds . 
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Call from FORTRAN : 



CALL TREMAIN (result} 
result Calculated CPU time remaining? stored in result. 

TIMES TAMP ROUTINES 

These routines are used by system accounting programs to convert between 
various representations of time, 

TSDT converts between times tamps and the date and time as ASCII strings. 
Call from FORTRAN: 

CALL TSDTlts r date, hhmmsSf 3883) 

ts Timestamp on entry (type integer) 

date Word to receive ASCII date mrrf/dd/yy 

hhmmss Word to receive ASCII time hhzmmtss 

SS88 Word to receive ASCII fractional seconds, 8888 

DTTS converts from date and time to timestamp . 
Call from FORTRAN: 

ts=DTTS (date t time) 

ts Timestamp corresponding to date and time (type integer) 

date ASCII date on entry in the form of mrrf/dd/yy 

time ASCII time on entry in the form of hhzmmiss 

On return, if ts=0, an incorrect parameter was passed to DTTS. 
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TSMT converts from a times tamp to the corresponding real-time clock value* 
Call from FORTRAN: 



irte^TSMT(ts) 



irta Real-time clock value corresponding to specified timestamp 

ts Timestamp to be converted (type integer) 



MTTS converts from a real-time clock value to the corresponding timestamp 
value . 

Call from FORTRAN: 



ts**M?TS (irta) 



ts Timestamp corresponding to real-time clock value (type 

integer) 

irta Real-time clock value 



UNITTS returns the number of timestamp units in a specified number of 
standard time units. UNITTS must be declared type integer. 

Call from FORTRAN: 



teKJNlTTS (periods , units) 



ts Number of timestamp units in periods and units (type 

integer) 

periods Number of timestamp units wanted in standard time units 

(that is, number of seconds, minutes, etc.); type integer. 

units Specification for the units in which periods is 

expressed. The following values are accepted: 'DAYS 1 !!, 
'HOURS'H, IMINUTES'H, 'SECONDS'H, , MSEC I H (milliseconds), 
•USEC'H (microseconds), 'USECIOO'H (100s of microseconds). 
Left- justified, blank-filled, Hollerith. 
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Example: 



t s=UNITTS ( 2 , 1 DAYS ' H) 



ts Number of time stamp units in two days 



CONTROL STATEMENT PROCESSING ROUTINES 

Control statement processing routines place control statement elements in 
appropriate memory locations to perform the specified operations. These 
routines, CRACK, PPL, and CEXPR, also can process directives obtained 
from some source other then the control statement file <$CS) . 



CONTROL STATEMENT CRACKING ROUTINES 

Control statement cracking routines take the uncracked image from the 
JCCCI field and crack it into the JCCPR field. The Job Communication 
Block (JCB) contains the control image in JCCCI. JCDLIT is a flag 
indicating whether or not literal delimiters are to be retained in the 
string. 

$CS, $CCS, and CCS are different entry points in the same routine. 



$CS does not abort the job if errors are encountered. 
Call from CAL: 



CALLV $CS 



Exit: 

(SO) ~0 No errors 
7*0 Errors 



$CCS,CCS aborts the job if errors are encountered. 
Call from CAL: 



CALLV $CCS 
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Call from FORTRAN: 



CALL CCS 



CRACKED PARAMETER LIST 

Control statement parameters are available to the user in the form of a 
cracked parameter list starting at location W8JCCPR in the JCB. 



Example : 



The following control statement appears in the cracked parameter list as 
described below (shaded area is binary zero} . 



VERB r KEYWORD 55 * THIS IS A LITERAL VALUE...*, 




0 8 16 24 32 40 48 56 63 


W@JCCPR+C 


V 1 E | R | B 1 //////////////////////////////// 


1 


/////////////////////////////////////////////////////// 1 017 


2 


K|E|Y|W|0|R|D I//////// 


3 


/////////////////////////////////////////////////////// 1 007 


4 


TlHjllSl |I|S| 


5 


A | |L|I|T|E|R|A 


6 


L| |V|A|L!U|E|. 


7 


. 1 . 037 



An internal code for each control statement separator or terminator is 
positioned in the last byte of odd-numbered words following keyword or 
parameter values in the cracked parameter list. 

Control statement scanning stops when a continuation separator or 
terminator is encountered. Thus, for continued control statements , the 
caller can call F$GNS again to scan the remainder of the control 
statement . 



Example; 

This is an example of a continued control statement. 

ACQUIRE , DK=dn , TEXT= 1 ABC 1 /\ 
'DBF'. 
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The first crack control statement (CCS) call results in the following 
cracked parameter list: 



16 



24 



32 



40 



48 



WQJCCPR+C 



1 
2 
3 
4 
5 
6 
7 
8 
9 



/////////////////////////////////////////////////////// I 017 



/////////////////////////////////////////////////////// I 007 



56 



63 



I 



I//////// 



I N I//////////////////////////////////////////////// 



I N i //////////////////////////////////////////////// 



/////////////////////////////////////////////////////// I 017 



T | 



I 



I //////////////////////////////// 



/////////////////////////////////////////////////////// I 007 



I B | 



I//////////////////////////////////////// 



/////////////////////////////////////////////////////// I 002 



The calling program can then interpret this portion of the control 
statement. The second CCS call replaces the cracked parameter list with: 



8 



16 



24 



32 



40 



48 



56 



63 



W0JCCPR+C 



I 



I//////////////////////////////////////// 



/////////////////////////////////////// //// //////////// I 037 



The current control statement image remains in unmodified form at 
location W3JCCCI in the JCB. 



GET PARAMETER ROUTINE 

The get parameter routine processes control statement parameter values 
from an already cracked control statement. If the statement has been 
continued across card images, GETPARAM automatically requests the next 
control statement and calls $CCS to crack it. Processing is determined 
by the rules set up by the Parameter Control Table (PCT) . 

The PCT indicates default values for unspecified parameters. Through the 
PCT, the caller also indicates the following. 

• If a parameter must be specified on the statement 

• If a parameter is positional or keyword 

• If a keyword parameter can have an equated value 
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• If a keyword parameter must have an equated value 

• If any parameters are allowed 
Call from FORTRAN : 



Call GETPbRm (table, number, param) 



table The Parameter Control Table (PCT) , dimensioned (5, number) 
and containing the following in each 5-element row. 

1. A left- justified r zero-filled keyword 

2. A default value for use if the keyword is missing 

3. A keyed value for use if the keyword is unqualified 

4. An initial subscript for use in output to param 

5. A limiting subscript for use in output to param 

If item 2 is negative, GETPARAM requires the keyword to be 
on the control statement. 

If item 3 is negative, GETPARAM does not allow the use of 
the keyword alone (as in "... , keyword, ... ") . 

Either item 2 or 3 can be 0; GETPARAM does not distinguish 
between zeros and any other positive values such as 
character strings, but the caller can test them after 
GETPARAM returns. 

If items 2 and 3 are 0 and 1, or 1 and 0 respectively, 
GETPARAM does not allow the keyword to be followed by an 
=. The keyword must be simply absent or present. 

If item 1 is a 64-bit mask (that is, 177777 7777 7777 7777 
7777B) , then the value given as the keyword is returned in 
the control table. When an entry of this type has been 
specified in the control table, the number of parameters is 
limited to one. 

If item 1 is given a value of 0, then the entry describes a 
positional parameter. Entries of this nature must be 
described in positional order. 

If bit 2 in item 4 (that is, 020000 0000 0000 0000 0000B) 
is set, the parameters following the keyword are defined to 
be secure and are edited out before the statement is echoed 
to the user's logfile. 



SR-0014 



7-49 



I 



number The number of parameters described in the control table • 
If given a value of 0, GETPARAM does not allow any 
parameters on the control statement* 

param An array sufficiently large to receive all the parameter 
values 

Call from CAL: 



CALLV $GPARAM 



(Al) table (Address) 

(A2) number (Actual number) 

(A3) params (Address) 



NOTE 

$GP is an alternate entry for CAL callers and provides 
a "no-abort" exit. Upon exit f SO-0 if no errors are 
detected* 



Example of control table definition in FORTRAN: 

INTEGER PERMFILE ( 2) PARAMS (15) , TABLE (5,4) , INPUT, LIBRARY (10) , 
LIST 

EQUIVALENCE ( PARAMS { 1) , INPUT) , 

* (PARAMS (2) , PERMFILE) , 

* (PARAMS (4) ,LIBRARY{1) ) , 

* (PARAMS (14) f LIST) 
DATA PARAMS/15*J0/ 

DATA (TABLE(I.l) , 1=1,5) /» I 'L, 'fclN'L, »$IN'L,1,1/, 

(TABLE (I ,2) ,I=l f 5)/ , P , L,0 f -l,2 r 3/ , 

(TABLE (1, 3) fl^USJ/'LIB'Lj-l, 1 $FTLIB 1 L, 4 , 13/ , 

(TABLE (I, 4) f I=l f 5)/ , LIST , L,0,l f 14,14/ 
CALL GETPARAM (TABLE, 4, PARAMS) 

This table (for a hypothetical program) tells GETPARAM that the only 
keywords to be accepted are I, P, LIB, and LIST. The -1 value means that 
P cannot appear alone (without an equal sign) and that LIB (with or 
without an equal sign) must appear in the control statement. 

In this table, only one word is provided for the I parameter; therefore, 
if I-xxx appears in the control statement, the option xxx must not 
exceed eight characters. The two words provided for the P parameter 
allow for the maximum of 16 characters or for two subparameters (up to 
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eight characters each) separated by a colon in the control statement. 
Ten words are provided for the LIB parameter so that up to ten 
subparameters (or five 2-word parameters) are allowed in the control 
statement. GETPARAM requires the keyword LIST to appear alone or not at 
all. If LIST is specified , the value returned in the Parameter Value 
Table is 1. LIST cannot be followed by an equal sign. 



NOTE 

The following two subparameters cannot be distinguished 
from one another in the P ARAMS table: 

A=A1234567:B1234567 (Two 8-character parameters) 

A=A1234567B1234567 (One 16-character parameter) 

Thus r the caller is responsible for restricting such 
cases • 

The output array P ARAMS must be as large as the largest 
subscript. If P ARAMS is initialized to zeros , the 
programmer can determine how many words are returned by 
GETPARAM for multiword parameters such as P and LIB. 



Since FORTRAN array numbering starts with 1, the array's base address is 
reduced by 1 in GETPARAM. Therefore , the CAL user must supply the table 
address + 1^ in order to use labels directly in lieu of the FORTRAN 
subscripts. 

GETPARAM aborts if the control statement violates either the standard 
control statement syntax rules or the additional rules imposed by the 
Parameter Control Table. If there are no errors, the array is filled 
with values from the control statement and/or with default values. The 
Parameter Control Table is not altered by GETPARAM. 



DIRECTIVE CRACKING ROUTINE 

The directive cracking routine reformats (cracks) a user-supplied string 
into verb, separators, keywords, and values. The cracked directive is 
placed in a user-supplied buffer and returns the status of the crack to 
the caller. CRACK can be called repeatedly to process a control 
statement across several records. 



t This is not true for $GP. 
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Call from FORTRAN: 



call cmcK{ibuf ,ilen, cbuf r clen,flag[,df lag]} 



ibuf Image of the statement to be cracked 

Hen Integer length (in words) of the image of the statement to 

be cracked. Maximum value is 10 words, 

cbuf Array to receive the cracked image 

clen Integer length in words of the array cbuf 



NOTE 

Each keyword or positional parameter should be assigned 
a separate word* Keywords or positional parameters of 
more than eight characters must be assigned one word 
for each eight characters plus one for any remaining 
characters if length is not a multiple of eight 
characters. Each separator must also be assigned a 
separate word* 



flag Integer variable to receive completion status. The Return 

Value flag has the following meanings. 

0 Normal termination 

1 No error; continuation character encountered. 

2 Invalid character encountered 

3 Premature end of input line 

4 CRACK buffer overflow 

5 Unbalanced parentheses 

6 Input buffer too large 

dflag Integer flag indicating that literal string delimiters are 
to be preserved in the cracked image. If set to 0 or 
omitted, quotes are not in the cracked string . If set to 
1, all quotes are included in the string. 



NOTE 

flag should be set to 0 before the first call to 

CRACK and not changed (except by CRACK) until after the 

last call to CRACK. 
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PROCESS PARAMETER LIST ROUTINE 



The process parameter list routine processes the keywords for a given 
directive. Processing is governed by the Parameter Description Table, 
This table has the same format as the table GETPARAM uses, except that 
the length of the table used by PPL is seven words with the extra two 
words unused • 



Call from FORTRAN: 



CALL PPUcbuf ,ctable , liable r outarray ,stattbl) 

cbuf Array to receive the cracked image 

c table ppl control table 



liable Number of 7-word entries in PPL control table 



outarray Array to receive parameter values 



stattbl 3-word completion status array. On the first-time call, 
the Return Status Table is initialized to 0, If PPL 
returns a non-normal status, and PPL is called again with 
the non-normal values left in, it attempts recovery. 



Array element Meaning 

Return status code: 

1 0 ttormal termination 

1 Required keyword not found 

2 Output keyword overflow 

3 Syntax error 

4 Unknown or duplicate keyword 

5 Unexpected separator encountered 

6 Keyword cannot be equated 

7 Keyword must have value 

8 Maximum of 64 keywords exceeded 

9 Invalid return status; cannot 
recover . 

2 Keyword in error 

3 Ordinal keyword value 



CRACK EXPRESSION ROUTINE 

The crack expression routine transforms an expression character string 
(one right-justified character per word) to a Reverse Polish Table. 
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Call from FORTRAN: 



CALL CEXPR (char, out, lmt 9 size) 



char Expression character string array (terminated by a zero 

byte) 

out Reverse Polish Table array for output 

Imt Upper limit to the size of the Reverse Polish Table 

size Actual size of the Reverse Polish Table on return 



An expression can contain a mixture of symbols, literals, numeric values 
and operators. Expressions handled by this routine are FORTRAN- like in 
syntax. The legal operators are listed later in this section. 

Operator hierarchy follows FORTRAN rules and does parenthesis nesting. 
Symbols are defined as 1- to 8-character strings having unknown value to 
CEXPR. CEXPR simply flags the strings for the caller. The first 
character cannot be numeric. Literals are 1 through 15 character strings 
enclosed by double quotes ( n ) . 



A character string consisting of numeric digits is taken as a 64-bit 
integer* A trailing B signifies a Boolean number. 



The following is the format of the Reverse Polish Table. 



8 



16 



24 



32 



40 



48 



56 



63 



ITEM 



|T I OC 



n 



Field 



Bits 



Description 



ITEM^ 0-55 15-character data item from the character string 

T 56-57 2-bit type field describing ITEM 

01 1- through 8-character symbol 

10 1-word binary value 

11 1- through 15-character literal string 
(delimiting double quotes not included) 

00 Null, OC is valid 
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Field Bits Description 

OC 58-63 6-bit operator code. 

Operator 
code (octal) Operator 



01 


.XOR. 


10 


.OR. 


20 


.AND. 


30 


.NOT. 


40 


.EQ. 


41 


.NE. 


42 


.LT. 


43 


• GT. 


44 


.LE. 


45 


.6E. 


50 


+ 


51 




52 


+ (unary) 


53 


- (unary) 


60 


* 


61 


/ 



CEXPR references the following internal routines: CEXERR, ITBLSTO, 
ITBLSYM, ITBLOC, LITERAL, ERR1, ERR2, PUTLINE. 



JOB CONTROL LANGUAGE SYMBOL ROUTINES 

The job control language symbol routines manipulate job control language 
(JCL) symbols for conditional JCL statements. 



JSYMSET allows the user to change a value for a JCL symbol. The value is 
the actual value given to the symbol, with no evaluation being performed. 

Call from CAL: 



CALLV $JSYMSET 



Entry: 

(SI) Symbol name 

(Al) Points to value 

(A2) Length of value 
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Call from FORTRAN: 



call JSYMSET (sy m, vat [, ten}) 



sym Valid JCL symbol name 

vat Actual value assigned to the symbol 

ten Length of vat in words (elements) 



JSYMGET allows user programs to retrieve JCL symbols. The JSYMGET 
routine also allows the creation of JCL symbols if they do not exist. 

Call from CAL: 



CALLV $JSYMGET 



Entry i 

(SI) Symbol name; left-justified, zero-filled. 

(Al) Where value is returned 

(A2) Number of words in the area that is to receive the value 
Exit: 

(A2) Actual length of the value 



Call from FORTRAN; 



CALL JSYMGET {sym, vat[, ten ] ) 



sym Valid JCL symbol name 



vat Receives the actual value of the symbol if the value buffer 

is large enough and the symbol currently has a value 

ten Length of the value buffer in words (elements) • ten is 

changed to the actual length of the symbol's value (less 
than or equal to the value buffer) . 



SKOL RUN-TIME SUPPORT ROUTINES 



SKOL run-time support routines include character-string manipulation, 
character -code translation, and error handling applications. 
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CHARACTER-STRING MANIPULATION ROUTINES 



I00DEL deletes a SKOL string or substring and returns the length of the 
resulting string. 



len= I OODEL (string , max, clen , fohar , lohar) 



ten New length of the string addressed by string 

string A SKOL string 

max Maximum size of the string 

clen Current length of the string 

fohar Index of the first character to be deleted 

lehar Index of the last character to be deleted 



IQOMVC replaces a SKOL string or substring with a single character and 
returns the length of the resulting string. 



13W=I00MVC (string, max, clen ,f 'char, lehar ,iohar, Inum) 



len New length of string addressed by string 

string A SKOL string 

max Maximum size of string 

clen Current length of string 

fohar Index of first character to be replaced 

lehar Index of last character to be replaced 

iehar Character to be inserted in place of deleted substring 

Inum SKOL source line number of call to I00MVC 

I00MVM replaces a SKOL string or substring with another SKOL string or 
substring and returns the length of the resulting string. 



len^IQOMVM (string, max, elen, fohar, lehar, sstri, s fohar, slehar, Inum) 
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ten 


New length of string addressed by string 


strinq 


A SKOL string 


max 


Maximum size of string 


clen 


Current length of string 


fchar 


Index of first character to be replaced 


I char 


Index of last character to be replaced 


s&tri 


Second SKOL string 


sfchar 


Index of first character in second string to be inserted 


slehar 


Index of last character in second string to be inserted 


Inum 


SKOL source line number of call to I00MVM 



CHARACTER-CODE TRANSLATION ROUTINES 

I00ORD returns the internal SKOL code for a given ASCII character. 



NOTE 

I00SETUP must be called before any call to I00ORD. 
I0OSETUP is described later in this section. 



ord=!00QBD (char, Inum) 

ord Ordinal number of the given character 

char ASCII character? left-justif ied, blank-filled. 

Inum SKOL source line number of the call to I00ORD 

10 OREAD reads a logical record in Al format and converts each word 
containing an ASCII character, left-justif ied, blank-filled, to its 
internal SKOL code (character ordinal) • Internal codes for characters 
are defined by a TYPE CHAR statement. 
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NOTE 



I00SETUP must be called before any call to IOOREAD* 
I00SETUP is described later in this section. 



CALL 1 0 OREAD ( dn , array ,size, fohar , I char , Inum) 

dn Name or unit number of the dataset to be read 

array Array to receive the character ordinals 

size Size of array 

fohar Index of first character position to be filled 

lehar Index of last character position to be filled 

Inum SKOL source line number of call to 10 OREAD 

I00WRITE writes characters defined by the TYPE CHAR statement and 
converts character ordinals (internal SKOL codes) to ASCII characters in 
Al format, left- justified, blank-filled, and then writes them as a 
logical record, 

CALL 1 0 OWRITE (dn , array , size 9 ford, I ord, Inum) 

dn Name or unit number of the dataset to be written 

array Array containing the character ordinals 

size Size of array 

ford Index of first ordinal to be output 

lord Index of last ordinal to be output 

Inum SKOL source line number of call to I00WRITE 
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IOOSETUP initializes a SKOL program's table (128 words long) for direct 
translation of ASCII character codes to internal ordinal numbers. 



CALL IOOSETUP (oi*d f Inum) 



ovd 



Highest ordinal number to be used in the calling program 



Inum 



SKOL source line number of the call to IOOSETUP 



ERROR-HANDLING ROUTINE 

I0OERR handles run-time errors in SKOL programs, writes an error message 
to $OUT and $LOG, and then terminates the job step* 

CALL I00ERR (ovd, Inum) 



ERROR PROCESSING ROUTINES 

Error processing routines issue logfile messages and abort the job. See 
the CRAY-OS Message Manual, publication SR-Q039, for the messages issued 
by these routines. 

ARERPft processes $ARLIB errors. 
Call from CAL: 

CALLV ARERP% 



ovd 



Ordinal number of a SKOL error 



Inum 



SKOL source line number where the call to I00ERR was 
inserted by the macro translator 



Entry: 
(SI) 



Error message ID defined in $3YSTXT r hBnnn 
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FTERP% processes $FTHB errors. 
Call from GAL: 



CALLS/ FTERP% 



Entry: 

(SI) Error message ID defined in $SYSTXT, FTnnn 



IOERP% processes $IOLIB errors. 
Call from CAL: 



CALLV I0ERP% 



Entry : 

(51) Error message ID defined in $SYSTXT, FTnnn 

(52) Unit identification, ASCII, left-adjusted 

(53) If nonzero, format FWA 

(54) Character position in format 

(55) If nonzero, string buffer FWA 

(56) Character position in string buffer 

(57) Mode ('INPUT 1 , 'OUTPUT 1 , etc*) 



NLERP% processes NAMELIST I/O errors* 



Call from CAL: 



CALLV NLERP% 



Entry: 

(51) Error message ID defined in $SYSTXT, FTnnn 

(52) Unit identification, Hollerith, left-justif ied, zero-filled 

(53) Record name 

(54) If nonzero, item name 

(55) If nonzero, address of string buffer 

(56) If nonzero, character position in buffer 

(57) Mode ("INPUT 1 , 'OUTPUT 1 , etc.) Hollerith, left-justif ied, 
zero-filled 
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NOTE 



If a format or string buffer address is provided, the 
format or buffer is listed on $OUT and, if possible, 
the error position is marked* 



SSCERP processes $SCILIB errors. Aborts with traceback. 
Call from GAL: 



CALLV $SCERP 



Entry: 

(SI) Error message ID defined in $SYSTXT, SCnnn 



SLERP% processes $SYSLIB errors and abort with traceback. 
Call from CAL: 



CALLV SLERP% 



Entry: 

(51) Error message ID defined in $SYSTXT, SLnnn 
If error message has two arguments: 

(52) Name of unit, ASCII format 

(53) ASCII descriptive word ( 'READ 1 , 'WRITE* , or program name of 
calling routine) ; blank-filled 

If error message has one argument: 
(S2) Dataset name or unit number 



UTERP% processes $UTLIB errors. 
Call from CAL: 

CALLV UTERP% 

Entry: 

(SI) Error message ID defined in $SYSTXT, UTnnn 
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BYTE AND BIT MANIPULATION ROUTINES 



Byte and bit manipulation routines move bytes and bits between variables 
and arrays, compare bytes, perform searches with byte count as a search 
argument, perform conversion on bytes, and pack and unpack bits. 



MOVE BYTES ROUTINE 

The STRMOV routine moves a specific number of bytes from one variable or 
array to another* The arguments num 9 isb, and idb must be greater 
than 0 for any data to be moved. The argument dest must be declared 
long enough to hold num bytes or spill will occur and data will be 
destroyed. 

Call from FORTRAN: 



CALL STBMOV (ere, isb, num, dest, idb) 



svc Variable or array of any type or length that contains the 

bytes to be moved. Bytes are numbered from 1, beginning at 
the leftmost byte position of eve* 

i8b Starting byte in the 8re string. Type integer variable, 

expression, or constant. Bytes are numbered from 1, 
beginning at the leftmost byte position of src* 

num Type integer variable, expression, or constant that contains 

the number of bytes to be moved 

dest Variable or array of any type or length that contains the 

string to receive the bytes 

idb Type integer variable, expression, or constant that contains 

the starting byte to receive the data. Bytes are numbered 
from 1, beginning at the leftmost byte position of dest* 



MOVE BITS 

The MOVBIT routine moves a specified number of bits from one variable or 
array to another. The arguments num, isb, and idb must be greater 
than 0 for any data to be moved. The argument dest must be declared 
long enough to hold num bits or spill will occur and data will be 
destroyed. 
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Call from FORTRAN 



CALL MOVBIT (svc f isb 9 num,dest ,idb) 



svo Variable or array of any type or length that contains the 

string of bits to be moved, 

isb Starting bit in the ere string. Type integer variable, 

expression , or constant. Bits are numbered from 1, 
beginning at the leftmost bit position of src. 

num Type integer variable, expression, or constant that contains 

the number of bits to be moved 

de&t Variable or array of any type or length that contains the 

string to receive the bits 

idb Type integer variable, expression, or constant that contains 

the starting bit to receive the data. Bits are numbered 
from 1, beginning at the leftmost bit position of dest. 



MOVE CHARACTERS ROUTINE 

MVC moves characters from one memory area to another. The source and 
destination strings can occur on any byte boundary. The move is performed 
one character at a time from left to right. The destination string can 
overlap the source string. 

Call from FORTRAN; 



CALL MVC(s 1 ,j lt S 2f j 2 ,k) 



SjL Word address of the Hollerith source string 

j\ Byte offset from the word address of the source string of 

the first byte of the source string (the high-order byte of 
the first word of the source string is byte number 1) 

s 2 Word address of the Hollerith destination string 



SR-0014 



7-64 



I 



32 Byte offset from the word address of the destination string 

of the first byte of the destination string (the high-order 
byte of the first word of the destination string is byte 
number 1) 

k Number of bytes to be moved 

For example , the first byte of an array can be copied throughout the array 
by the following call (where K is the length of the array in bytes) ♦ 



CALL MVC(ARRAY,1, ARRAY r 2, K-l) 



REPLACE BYTE ROUTINE 

PUTBYT replaces a specified byte in a variable with a specified value. 
The high-order 8 bits of the first word of the variable is called byte 1. 

Call from FORTRAN: 



CALL putbyt {string , position, value) 



string The address of a variable* The variable may be of any type 
except CHARACTER. 

position The number of the byte to be replaced. The parameter must 
be an integer greater than or equal to 1. 

value The new value to be stored into the byte. The parameter 
must be an integer with value between 0 and 255 ♦ 

If PUTBYT is called as an integer function (having been properly declared 
in the user program) , the value of the function is the value of the byte 
stored. 

If position is less than or equal to 0, no change to the destination 
string is made; the function value is -!♦ 
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COMPARE BYTES FUNCTION 



The KQMSTR function performs an unsigned, twos complement compare of a 
specified number of bytes from one variable or array with a specified 
number of bytes from another variable or array* The arguments num, 
i8b, and iab have no size limits. 

Call from FORTRAN: 



ik 55 KOMSTR {eve , isb,num, dest , idb) 



ik Type integer result. Contains 0 if the strings &?c and 

dest are equal. Contains 1 if arc > dest and 
contains -1 if btg < dest* 

8rc Variable or array of any type or length containing the first 

string to compare 

i&b Starting byte in the arc string. Type integer variable, 

expression, or constant. Bytes are numbered from 1, 
beginning at the leftmost byte position of arc. 

num Type integer variable, expression, or constant that contains 

the number of bytes to compare. 

deat Variable or array of any type or length containing the 

second string to compare 

idb Type integer variable, expression, or constant that contains 

the starting byte. Bytes are numbered from 1, beginning at 
the leftmost byte position of dest* 



SEARCH BYTES ROUTINE 

The FINDCH subroutine searches a variable or array for the occurrence of a 
specified character string. The result is equal to the byte count in the 
variable or array where the string was found, or equal to 0 if no string 
was found. 

Call from FORTRAN: 



CALL FINDCH [ohra , len, str , Is , nb, ifnd) 



ehvs Variable or array of any type or length containing the 

search string 
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ten Length of the search string in bytes (itiust be from 1 to 

256). Type integer variabie f expression, or constant. 

str Variable or array of any type or length that is searched for 

a match with ekrs 

Is Starting byte in the sti* string. Type integer variable, 

expression, or constant. Bytes are numbered from 1, 
beginning at the leftmost byte position of stv* 

nb Number of bytes to be searched. Type integer variable , 

expression, or constant. 

ifnd Type integer result 



ASCII TO INTEGER ROUTINE 

The CHCONV subroutine converts a specified number of ASCII characters to 
an integer value. Blanks in the input field are treated as zeros. A 
minus sign encountered anywhere in the input field produces a negative 
result. Input characters other than blank, digits 0 through 9, minus 
sign, or more than one minus sign, produce a fatal error. 

Call from FORTRAN 



CALL CHCONV {sve fisb, nurn, iv) 



sve Variable or array of any type or length containing ASCII 

data or blanks 

isb Starting character in the svc string. Type integer 

variable, expression, or constant. Characters are numbered 
from 1, beginning at the leftmost character position of 
sr<3. 

nurn Number of ASCII characters to convert. Type integer 

variable, expression, or constant. 

ir Type integer result 
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INTEGER TO ASCII ROUTINES 



The BICONV subroutine converts a specified integer to an ASCII string. 
The string generated by BICONV is blank-filled, right-justified, and has a 
maximum width of 256 bytes* If the specified field width is not long 
enough to hold the converted integer number, left digits are truncated and 
no indication of overflow is given. If the number to be converted is 
negative, a minus sign is positioned in the output field to the left of 
the first significant digit. 

The BICONZ subroutine is the same as BICONV except that the output string 
generated is zero-filled, right- justified. 



Call from FORTRAN; 



call BicONvHntfdestrisbtlen) 
CALL BICONZ {%nt 9 dest 9 tsbf ten) 



int Type integer variable, expression, or constant containing 

the integer value to be converted 

dest Variable or array of any type or length to contain the ASCII 

result 

isb Starting byte count to generate the output string. Type 

integer variable, expression, or constants Bytes are 
numbered from 1, beginning at the leftmost byte position of 
dest. 

ten Desired length of the output string. Type integer variable, 

expression, or constant. 



PACK, UNPACK 

The PACK and UNPACK routines compress and expand stored data. 

PACK takes the 1, 2, 4, 8, 16, or 32 rightmost bits of several partial 
words and concatenates them into full 64-bit words. The formula for the 
number of full words is shown in equation 1. 
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Equation 1: 

n=(nw x nbite) /64 



nw Number of partial words 

nbitB Number of rightmost bits of each partial word that is useful 
data 

n Number of resulting full words 



Equation 1 restricts nw x nbits to a multiple of 64. 
Call from FORTRAN: 

CALL PhCK(p,nbits r u,nw) 



p Vector of packed data 

nbits Number of rightmost bits of data in each partial word* Must 
be 1, 2, 4 f 8/ 16, or 32. 

u Vector of partial words to be compressed 

nw Number of partial words to be compressed 



UNPACK reverses the action of PACK and expands full words of data into a 
larger number of right-justified partial words. This routine assumes nw 
x nbits to be a multiple of 64. 

Call from FORTRAN: 



CALL UNPACK (p r nbit8,U, rflti) 



p Vector of full 64-bit words to be expanded 

nbits Number of rightmost bits of data in each partial word. Must 
be l r 2, 4, 8 f 16, or 32. 

u Vector of unpacked data 

nw Number of resulting partial words 
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MISCELLANEOUS SPECIAL PURPOSE ROUTINES 



Each miscellaneous routine described below has a separate purpose; 
therefore, the routines are not grouped. 



ACTTABLE returns Job Accounting Table ( JAT) . 
Call from FORTRAN: 



CALL ACTTABLE (array , coun t ) 



array An array 

count Count; the first count words of the JAT are returned in 

the array. If count is greater than the size of the JAT, 
the array is padded with zeros. 



DRIVER allows a user to directly program a CRAY channel on an IOS . 

This is a privileged function available to all single-tasked jobs. It is 

prohibited to multitasking jobs. 

Call from FORTRAN: 



CALL DRIVER (array , lent ry , status) 



array First element of the integer parameter block array. The 
array is lentry words long. In all cases, FUNC, PLEN and 
LN are required in the parameter block and COSS is returned 
in the parameter block ERPB. DP is always sent to the 
driver and returned to the user. 

For the FORTRAN user, FUNC, DIR and COSS are literal strings 
(i.e. set FUNC to 'CFNSOPE 1 and DIR to 'Dn^INP 1 to open an 
input channel. , DRS$RSV I in COSS means the channel is 
reserved for another job) . 

•CFNSOPE* subf unction opens a channel; a job cannot access a 
channel until it opens the channel • DRNM, DRTO, DIR, and 
OPD are required. 

, CFN$CLS" subf unction closes a channel. Any open channels 
are closed during termination. DIR is required. 



t This capability is available only on the MIOP. 
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1 CFN$HD 1 , , CPN$RDH , f 1 CFN$RDD 1 subfunctions read data, BAD 
and DLEN are required; TLEN is returned. For read, either 
the channel is read to central memory or data is moved from 
IOS buffer memory to central memory (if a read/hold was done 
prior to this read) * For read/hold, a second read is 
performed and the data is held in buffer memory for a 
subsequent read. For read/read , a second read to central 
memory is done. 

, CFN$WT , # , CFN$WTH , f 1 CFN$WTD 1 subfunctions write data. BAD 
and TLEN are required; TLEN is returned. For write, data is 
written to the channel from central memory or buffer memory 
(if a write/hold was done prior to this request). For 
write/hold, a second buffer of data is moved to and held in 
buffer memory for a subsequent write. For write/write a 
second write is performed from central memory. 

, CFN$DMIN , - , CFN$DMAX f subfunctions are defined by the 
driver. DFP and DIR are required. 

lentry Length of the parameter block entry in array; integer 
variable set by the user. 

status Status; integer variable set by the system. On return, 
status is 0 if no errors occurred and the job must poll 
COMS for nonzero. When CQMS is nonzero, the driver has 
completed the request and the driver status is in DRS. See 
the individual driver specifications for driver status. If 
status is nonzero on return, COSS contains the error code 
and the request is not sent to the driver. 

If no errors occurred and if status is nonzero on return, 
COSS contains the error code. 



ECHO allows the user to turn on and off the classes of messages to the 
user logfile. 

Call from FORTRAN: 



call echo ( ' ON 1 L [ r param-array] , ? off 1 L [ ,param-array] ) 



pararrnarray 

Array of message class names or 1 ALL 1 . Message class names 
are defined in the CRAY-OS Version 1 Reference Manual, 
publication SR-0011. 
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ERECALL allows a job to suspend itself until one or more selected events 
occur. This routine is available to all single-tasking jobs; it is 
prohibited to multitasking jobs. 

When event monitoring is enabled, the system monitors selected events for 
a job, keeping track of which ones have occurred. Monitoring is disabled 
at the beginning of each job step and can be enabled by making a system 
request, specifying the events to monitor. Once monitoring is enabled, a 
job can make a system request to change the events that are to be 
monitored, get a map indicating which of the monitored events occurred, go 
into event recall until one of the selected events occurs, or disable 
monitoring. 

When monitoring is enabled, a map of occurred events is returned to the 
user and discarded by the system. If monitoring was disabled when the 
enable occurred, the map is 0. 

When the events to be monitored are changed, a map of occurred events is 
returned to the user and discarded by the system. 

When a map of occurred events is requested, the map is returned to the 
user and discarded by the system. 

When recall is requested and the map of occurred events is 0, the job is 
suspended for an event until one of the events occurs. If the map is 
nonzero, the map is returned to the user immediately and discarded by the 
system. 

When recall is disabled, the map of occurred events is discarded by the 
system. 

Call from FORTRAN: 



CALL ERECALL (fun c , status f sevents ,to r oevents , levents) 



funo Integer variable set by the user to define what information 

or action is requested. 

•DISABLE 1 Disables event monitoring. All other words 
ignored. 

1 ENABLE * Enables event monitoring or changes the events 
to be monitored, levents and sevents are 
required. If levents is 0, timeout is the 
only enabled event. Timeout is enabled in 
order to prevent a job remaining indefinitely 
in recall, levents and oevents are 
returned by the system, to is ignored. 
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'RECALL 1 Places the job in recall. An error is 
returned in status if monitoring is 
disabled, to is required, sevents is 
ignored, levents and oevents are set by 
the system. If to is 0, an 
installation-defined default, I8T0DEF, is 
used. If to is specified, but less than the 
installation defined minimum, I8TQMIN, the 
installation minimum is used with no 
notification ♦ If levents is 0 on return, 
timeout is the only event that occurred. 



'RETURN 1 Requests levents and oevents be set by the 

system; all other words are ignored. An error 
is returned in status if monitoring is 
disabled. 



status Status; integer variable set by the system. Status is 0 
if no errors occurred; otherwise, see the parameter block 
ERPB definition for error codes. The codes are returned as 
blank-filled literal strings (for example, ERER$BPN will be 
returned as 'ERER$BFN'). 



sevents Integer array set by the user containing the events to be 
monitored, levents is the number of events specified in 
sevents* The events can be selected from the following. 



•IJ 1 Inter- job message received 

1 UO 1 Unsolicited operator message received 

'OR 1 Operator reply received* 



The following are privileged: 

'CH 1 Channel driver done 

'IQ f SDT placed in Input queue* 

'0Q f SDT placed in Output queue 



to Timeout duration in milleseconds (rightmost 24 bits) ; 

integer variable set by the user. 

oevents Integer array set by the system to the occurred events. 
levents is the number of event words that have been 
placed in oevents by the system. See sevents for 
possible values. 



t Deferred implementation 
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levents Integer value specifying the number of events in either 
sevents or oevents. For ENABLE, the user sets levents 
to the number of event words that the user has placed in 
sevents. On return from ENABLE, RECALL, and RECALL 
levents is the number of event words that the system has 
placed in oevents. 

GETB1 returns the contents of register Bl (address of calling subroutine 
name) in register SI* 

Call from FORT AN: 



jM—GETBI 



bl Calling subroutine name address (Bl) 



GETLPP returns the lines per page from field JCLPP of the JCB in register 
SI. 

Call from FORTRAN: 



lpp*GETLPP( ) 



Ipp Lines per page (type integer) 



ICEIL is an integer function which returns the integer ceiling of a 
rational number represented as two integer parameters. 

Call from FORTRAN; 



i»ICEIL(j,fc) 



3 The numerator of a rational number 

k The denominator of a rational number 

The value of the function i is the smallest integer larger than or equal 
to s/k. 



IGTBYT extracts a specified byte from a variable. The high-order 8 bits 
of the first word of the array are called byte 1* The value of the byte 
is returned as an integer value between 0 and 255. 
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Call from FORTRAN: 



by £<2=IGTBYT (string, position) 



string Address of an array; the array can be of any type except 
CHARACTER. 

position Number of the byte to be extracted. Must be an integer 
larger than or equal to 1. If position is less than or 
equal to 0, the function value returned is -1. If 
position is greater than 0 f the function value is an 
integer between 0 and 255, 



IJCOM allows a job to communicate with another job. This feature is 
available to all single-tasking jobs. Inter- job communication is 
prohibited to multitasking jobs. 

Call from FORTRAN : 



CALL IJCOM (array $ larray , lentry , nentry , status) 



array First element of the integer parameter block array* An 
installation-defined maximum number of parameter blocks 
(I@MPBS) can be specified in array. The array is larray 
words long and each of the nentry parameter blocks in it 
is lentry words long. See the ERPB table definition for a 
description of a parameter block. The FORTRAN user ignores 
LINK; the system links the entries together for the user. 
In all cases , FUNC, RID, and PLEN are required in each 
parameter block and STAT is set in each parameter block by 
the system. 

For the FORTRAN user, FUNC and STAT are literal strings (for 
example, set FUNC to 'IiD^OFEN 1 to open a path. 'UMSSBP 1 
in STAT means the path was busy) . 

f IJM$NOP' Subfunction is a no op. 

, IJM$REC f Subfunction marks the job as receptive. RCB 
is required; all other words are ignored* 

■IJ^OPEN 1 Subfunction initiates an attempt to open a 
communication path with another job. HLEN, 
TID, and NCB are required; all other words 
are ignored. 
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I IJM$ACCE I 



Subf unction accepts a request from another 
job to open communication. TID, HLEN, and 
NCB are required; all other words are ignored* 



■IJMSREJE' Subf unction rejects a request from another 

job to open communication, TID is required; 
all other words are ignored. 



, IJM$SNDM I Subfunction sends a message to another job, 
NCB, TID, BADD and BLEN are required; all 
other words are ignored. 



V IJM$SNDL V Subfunction sends a message to an attached 
job's logfile. This is a privileged 
function, TID, OVR, FCS, FCU, CLS and BADD 
are required; all other words are ignored, 

' IJMfCLOS 1 Closes a communication path. Either NCB and 
TID or neither are required; all other words 
are ignored. If NCB and TID are specified 
only the path determined by RID and TID is 
closed; otherwise all communication paths 
with RID are closed. 



■IJM$END' Subfunction marks the job as not receptive. 
All other words are ignored. Existing 
communication paths are not affected. 



larray Length of array; integer variable set by the user. 

I en try Length of each parameter block entry in array; integer 
variable set by the user. 

nentry Number of parameter blocks in array; integer variable set 
by the user. Default is 1. 



status Status; integer variable set to 0 if no errors occurred. 

If status is nonzero, STAT contains the error code. If 
multiple parameter blocks are used, all STAT fields must be 
examined if status is nonzero. 



INS ASCI % inserts ASCII parameters into a message. Insertion is 
controlled by the Message Control Table (MCT) • 

Call from CAL: 

CALLV INSASCI% 
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Entry: 

(51) Message number; used as an offset into the MCT to select the 
entry (message) to be processed* 

(52) Base address of parameters to be inserted* Parameters must 
be in the order defined by the parameter control entry 
(PCE) . Parameters can span words, and each parameter is 
assumed to be right-justified. See figures 7-2 and 7-3. 

(53) Base address of the MCT. The format of the MCT is shown in 
figure 7-4. 

Exit: 

The message assembled in the destination buffer, unless the message 
number is out of range or the MCT is improperly defined, in which 
case, error message SLOOO is issued and the routine aborted 



Entry (one per variation in message format) : 

0 8 16 24 32 40 48 56 63 



NP I ///////////////////////////////// 1 PCA 



///////////////////////////////////////\ SW I SB | LEN 



Figure 7-3. Parameter control entry 
Field Bits Description 

PCSW 40-45 Starting word in text (0, 1,.*.) 

PCSB 46-51 Starting bit in starting word (0...63) 

PCLEN 52-63 Length in bits (maximum is 64 bits) 



Figure 7-2. Parameter Control Table 
Field Bits Description 

PCNP 0-7 Number of parameters to be inserted 

PCPCA 40-63 Address of parameter control entry (PCE) 

Entry (one per parameter) : 

0 8 16 24 32 40 48 56 63 
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Header : 



Entry: 



Field 

MCNM 

MCDBA 

MCPCA 

MCPCO 

MCMWL 

MCMWA 



0 8 


16 24 


32 40 


48 56 


63 


NM | 


DBA 




PCA 




0 8 


16 24 


32 40 


48 56 


63 


PCO | /////////////////////////// 1 MWL I 


MWA 





Figure 7-4 • Message Control Table 

Bits Description 

0-7 Number of messages defined in MCT 

8-31 Address of buffer in which to assemble message 

40-63 Address of Parameter Control Table (PCT) 

0-7 Offset into PCT; selects desired entry. 

36-39 Message length in words 

40-63 Message address in words 



JNAMJE returns job name* 
Call from FORTRAN: 



name* JNAME (result) 



name Job name; left- just if ied with trailing blanks. 

result Returned job name 



LGO loads an absolute program from a local dataset containing the binary 
image as the first record. The loaded program is then executed. Control 
does not return to LGO. 

Call from CAL: 



CALLV $LGO 



Entry : 

(SI) Dataset name containing the absolute load module 
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Call from FORTRAN: 



CALL LGO( v cfa f L) 



dn Dataset name containing the absolute load module 



LOC returns memory address of specified variable or array* 
Call from FORTRAN: 



addi>es8**ux: (arg) 



address Argument address 

arg Argument whose address is to be returned 



LOGECHO writes the last line formatted by $WFD as a message to the $LOG 
file. 

Call from FORTRAN: 



CALL LOGECHO 



Entry : 

A WRITE or PRINT statement has previously been executed in a 
FORTRAN program, or a WRITE or OUTPUT statement has been executed 
previously in a SKOL program, so that the characters written still 
remain in $WFD f s local buffer. The character string should end 
with a period. The first period encountered ends the message. 
Exit: 

The message has been written to $LOG (using REMARK2) unless $WFD's 
buffer contains nothing but blanks after the print control 
character in the buffer. 



MEMORY determines or changes a job's memory allocation and/or mode of 
field length reduction. 



SR-0014 



7-79 



I 



Call from FORTRAN : 



CALL MEMORY {code, value) 



code Determines what information or action is requested 

(blank-filled) . 

'UC value specifies the number of words to be added to (if 

value is positive) or subtracted from (if value is 
negative) the end of the user code/data area. 

r FL' value specifies the number of words of field length to 

be allocated to the job. If FL is specified and value 
is not, the new field length is set to the maximum 
allowed the job. 

'USER 1 The job is put in user-managed field length reduction 
mode, value is ignored. 

'AUTO 1 The job is put in automatic field length reduction mode. 
value is ignored. 

'MAXFL' The maximum field length allowed the job is returned in 
value* 

1 CURFL 1 The current field length is returned in value* 

1 TOTAL 1 The total amount of unused space in the job is returned 
in value. 

value An integer value or variable when code is 'UC or 'FL' * 

An integer variable that is to contain a returned value if 
code is 'CURFL', 'MAXFL*, or 'TOTAL* • 

Memory can be added to or deleted from the end of the user code/data area 
by using the 'UC 1 code. If the user code/data area is expanded, the new 
memory is initialized to an installation-defined value. 

The job's field length can be changed by using the 'FL 1 code. The field 
length is set to the larger of the requested amount rounded up to the 
nearest multiple of 512 decimal words or the smallest multiple of 512 
decimal words large enough to contain the user code/data, LFT, DSP and 
buffer areas. The job is placed in user-managed field length reduction 
mode for the duration of the job step. 

The job's mode of field length reduction can be changed by using either 
the 'USER' or 'AUTO 1 code. When 'USER* code is specified, the job is 
placed in user mode until a subsequent request is made to return it to 
automatic mode. When AUTO code is specified, the job is placed in 
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automatic mode and the field length is reduced to the smallest multiple 
of 512 decimal words that can contain the user code/data, LFT, DSP, and 
buffer areas. 

The job's maximum or current field length can be determined by the 
■MAXFL 1 or 'CURFL 1 code. The total amount of unused space in the job can 
be determined by the f TOTAL 1 code. 

The job is aborted if filling the request would result in a field length 
greater than the maximum allowed the job. The maximum is the smaller of 
the total number of words available to user jobs minus the job's JTA or 
the amount determined by the MPL parameter on the JOB statement. 

Examples : 



CALL MEMORY ( 1 FL ' ) 



The job's field length is set to the maximum allowed the job and the job 
is placed in user mode for the duration of the job step. 



CALL MEMORY ( 1 AUTO 1 ) 



The job's field length is reduced to a minimum and the job is placed in 
automatic mode. 



CALL MEMORY ('UC, -5) 
CALL MEMORY { ? UC ,IVAL) 



where IVAL is -5 
The job's user code/data area is reduced by five words. 

NACSED returns edition number for permanent dataset just accessed by CALL 
ACCESS ( DN=c?7? ) . 

Call from FORTRAN: 



£<2= NACSED ( ) 



ed Edition number in binary form 
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OPTION changes the user-specified options for a job. 
Call from FORTRAN: 



CALL OPTION (['LPP'L, MS'L] [ , 'STAT 1 , I' 0 **' |]) 

I 'OFF 1 I 



OVERLAY loads overlays and transfers to the overlay address (see CRAY-OS 
Version 1 Reference Manual, publication SR-0011, for details of the 
OVERLAY routine)* 



Call from FORTRAN: 



CALL OVERLAY (dn f lev l9 lev 2 I, recall] ) 

dn Dataset in which overlay resides 

lev± Overlay level 1 (LEVI) 

lev 2 Overlay level 2 (LEV2) 

recall Optional message: RECALL-DON 1 T RELOAD IF IN MEMORY. If 
the overlay is already in memory, use the overlay that is 
already there. 



PERF provides an interface to the hardware performance monitor feature on 
the CRAY X-MP mainframe. Thirty-two counters are available, arranged 
into 4 groups of 8 counters each. (See table 7-1.) Only one counter can 
be accessed at a time. 



Call from FORTRAN: 



CALL PERF if unc, group, buffer 9 bufl) 



func Performance monitor function. Either an integer function 

number (PM$xxx, where xxx is the function name) , or one 
of the following ASCII strings, left- justified, and 
zero-filled. 



•O^L Enable performance monitoring. 

■OFF'L Disable performance monitoring. 



1 REPORT V L Report current performance monitor statistics, 
1 RESET 1 L Report current statistics, then clear 
performance monitor tables. 
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group Performance monitor group number (integer). See table 7-1 
for group numbers and their corresponding counters and 
counter contents. 

buffer First-word address of a performance monitor request 
buffer. 



bufl 



Number of words in the buffer array 



The PERF request block format contains a fixed header and a variable 
number of subb locks following the header. The first three words of the 
header are set in subroutine PERF before calling the system, while the 
remaining words in the header are returned by the system. 

The words in the block header allow one to analyze the information 
returned in the subblocks without the use of constants, allowing programs 
to continue to execute correctly when the contents of the header or 
subblocks change. 



Block header format: 
0 8 



0 

a 
. 

11 



16 



24 



32 



40 



48 



56 



Block header 



63 



Field 


Word 


Description 


HMRSF 


0 


Subf unction (PM$ON,PM$OFF, PM$REP, PM$RST) 


HMRGN 


1 


Group number (0 through 3) for PM$ON 


HMRNW 


2 


Length of request block 


HMRNU 


3 


Number of words used 


HMRBH 


4 


Number of words in block header 


HMRTS 


5 


Set nonzero if block too small 


HMRCT 


6 


Offset to first group counter in subblock 


HMRCP 


7 


Offset to first group accounted cycles 


HMRGE 


8 


Length of counter group entry in subblock 


HMRNC 


9 


Number of counters in each group entry 


HMRNG 


10 


Number of groups in each subblock 


HMRLE 


11 


Length of subblock entries 
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Timing subblocks are returned for every REPORT and RESET call. Each 
subblock contains hardware performance monitor data from a single COS user 
task. 



The address of the first timing subblock is at (BLOCK FWA) + (contents of 
block header field HMRBH) , with the next following (contents of block 
header field HMRLE) word after the first. Subblocks end when the offset 
to the next block would start after (contents of block header field HMRNU) 
words. 



Each subblock contains a 2-word header, with fields HMTN and HMGRP- HMTN 
is the COS user task number associated with the subblock. 



HMGRP is the last hardware performance monitor group number active for the 
subblock. 



Within the subblock, there are (contents of block header field HMRNG) 
performance monitor groups reported. Each group report consists of two 
fields: counters associated with the group, and the number of CPU cycles 
that were accounted for while the specified monitor was active. The 
offset to the first group counter is (contents of block header field 
HMRCT) words into the subblock; there are (contents of block header field 
HMRNC) counters for each performance monitor group. The offset to the 
first group's accounted CPU cycle is at (contents of block header field 
HMRCP) . 

Timing groups within a subblock follow each other by (contents of block 
header field HMRGE) words. 



Subblock 


format: 






0 

. 

37 


0 8 


16 24 32 40 48 56 


63 


Subblock 


Field 


Word 


Description 




HMTN 


0 


User task number 




HMGRP 


1 


Latest performance monitor group number 




HMCNTO 


2-9 


Group 0, counter 0 through 7 




HMCCYO 


10 


Group 0 accounted CP cycles 




HMCNTl 


11-18 


Group 1, counter 0 through 7 
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Field 


Word 


Description 


HMCCY1 


19 


Group 1 accounted CP cycles 


HMCNT2 


20-27 


Group 2, counter 0 through 7 


HMCCY1 


28 


Group 1 accounted CP cycles 


HMCNT3 


29-36 


Group 3, counter 0 through 7 


HMCCY1 


37 


Group 1 accounted CP cycles 



$RBN and RBN convert trailing blanks to nulls. 
Call from CAL: 

CALLV $RBN 

Entry: 

(SI) Argument to be converted 
Exit: 

(SI) Result of conversion 
Call from FORTRAN: 

noblanks=*'8EM {blanks) 

blanks Argument to be converted 
noblanks Argument after conversion 
$RNB and RNB convert trailing nulls to blanks* 



NOTE 



FORTRAN programs using RBN or RNB must specify the 
function to be type integer. 
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Table 7-1. Performance counter group descriptions 





ir e t £ ozr iua nc e 








uesc r xp t ion 






Number of: 




0 


Instructions issued 




1 


CPs holdina issue 




2 


Fetches 


o 


3 


I/O references 




4 


CPU references 




5 


Floafcinci'-Doint add ooerafcions 




6 


Floafcina^ooint mulfciolv operations 




7 








Hnld is^iif* florid ife ions • 




0 


Semaphores 




J. 






2 


A registers and functional units 


T 
J. 


O 


o registers anu runctionai units 






V LC^XuLCL O 






T/ f nn/^^ i Ana 1 nni t*c 
V J- Ullto IXUiiaX U11XU9 










7 








Number of: 




0 


Fetches 




i 

X 


bCdidL reierences 




2 


Scalar conflicts 


*> 


«5 


I/O references 




ji 
4 


l/u conn lets 




c 

D 


clock reicLcnccs 




/; 
o 


X5XOCK COillllCtb 




7 


Vector memory references 






Number of; 




0 


000 - 017 instuctions 




1 


020 - 137 instructions 




2 


140 - 157 9 175 instructions 


3 


3 


160 - 174 instructions 




4 


176 , 177 instructions 




5 


Vector integer operations 




6 


Vector floating-point operations 




7 


Vector memory references 
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Call from CAL: 



CALLV $RNB 



Entry: 

(SI) Argument to be converted 
Exit: 

(SI) Result 

Call from FORTRAN: 



blank s~BNB (noblanks) 



blanks Argument after conversion 
noblanks Argument to be converted 



REMARK enters a message in the user and system logf iles preceded by a 
message prefix, , UT008 I . REMARK allows a maximum of 71 characters. 

Call from FORTRAN: 



CALL REMARK (message) 



message Message terminated by a zero byte or a 71-character message 

REMARK 2 enters a message in the user and system logf iles. REMARK 2 allows 
a maximum of 79 characters including message ID. 

Call from FORTRAN: 



call REMABK2 (message) 



message Message terminated by a zero byte or maximum of 79 characters 



REMARKF enters a message in the user logfile. Up to 12 variables can be 
passed in arguments 2 through 13. The variables must be of type integer, 
real, or logical so that they occupy only one word each. The message is 
prefixed by 'UTOOg 1 unless the caller supplies a prefix. The caller is 
judged to have supplied a prefix if the characters *b-b l where fr=blank, 
appear in columms 6 through 8 of the formatted message. 
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Sample FORTRAN calling sequences: 

10030 FORMAT ( f CA001 - ' , 14, 1 errors') 
ASSIGN 10030 TO LABEL 
CALL REMARKF (LABEL, IERRCNT) 

10770 FORMAT ('PD001 - ACCESS AS,A7, 1 ED=\ 14, ■;•) 
ASSIGN 10770 TO LABEL 

CALL REMARKF (LABEL, DN(1), DN(2) , ED) 
Call from FORTRAN : 



CALL REMARKF (var,fvar ¥ [ ,fvar 2 t . . -fvar 12 ] ) 



var Variable containing the address of a format statement for 

ENCODE 

fvar Address of variable 

$SEGRES initializes execution of a segmented program* 

$SEGCALL services intersegment subroutine calls in a segmented program. 

These routines require the creation of a Segment Description Table (SDT) 
whose address is stored in /$SEGRES/. Calls to these routines are made 
through code modifications performed by SEGLDR. These routines should 
not be called directly by a user program* 



SSWITCH tests sense switch* 
Call from FORTRAN: 



CALL SSWITCH (swnum, result) 



swnum Switch number (integer) 

result Value is 1 if switch value ranges from 1 to 6 and switch is 
on. Value is 2 if switch value is less than 1 or greater 
than 6 or if switch is off (integer) . 
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SYSTEM makes requests of the operating system. 
Call from FORTRAN: 



STATUSES YSTEM {function , argi , arg 2 ) 



Executive request number 

Optional argument (required by some requests) 
Optional argument (required by some requests) 
Status returned in SO (function dependent) 

TR translates a string in place from one character code to another using 
a user-supplied translation table. The same size characters are assumed. 

Call from FORTRAN: 



CALL HK(8,j,k 9 table) 



s First word of an array containing characters to be 

translated 

3 Byte offset within array s where the first character to 

be translated occurs 

k Number of characters to be translated 

table Translation table 

The translation table must be considered a 256-byte vector. As each 
character to be translated is fetched, it is used as an index into the 
translation table. The new value of the character is the contents of the 
translation table byte addressed by the old value. (The first byte of 
the translation table is considered to be byte 0.) 



WFBUFFER returns a character from the output buffer belonging to the $WFD 
module. (This buffer contains the last line formatted by ENCODE, WRITE, 
or PRINT. Each word in the buffer contains a character in FORTRAN Rl 
format.) 



function 

arg 2 
STATUS 
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Call from CAL: 



CALL WFBUFFER, (apg) 



Entry: 

org Index of the desired character 
Exit: 

(SI) Requested character right-justified, zero-filled 



Users can call procedures from a CFT or CAL program, using the P$CSP 
system call. FORTRAN users should use the SYSTEM routine with the 
appropriate parameters. CAL users should set up the call parameters in 
the proper registers and EX. 
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PASCAL SUBPROGRAMS 



8 



INTRODUCTION 

Pascal subprograms are procedures and functions that reside in the Pascal 
runtime library, $PSCLIB. Some of these subprograms are implicitly 
called from Pascal programs. For example, the Pascal source statement 

WRITE (10) 

is translated into a call on P$WI. To explicitly call such a subprogram, 
declare it at the beginning of the Pascal program with an external 
directive. Each subprogram that can be explicitly called is listed with 
its accompanying external directive. 

Some of the Pascal subprograms are called from CAL only; their parameter 
linkages are such that they cannot be called directly from Pascal 
programs. For details of Pascal program organization, refer to the 
Pascal Reference Manual, CRI publication SR-0060. 



P$$$HPAD 

P$$$HPAD returns the address of the program's heap control block, which 
is the data area used by P$MEMRY, P$NEW rnd P$DISP to control use of the 
dynamic variable storage area. P$$$HPAD is used only within these 
routines. No parameters are required. 



FUNCTION P$$$HPAD: INTEGER; EXTERNAL; 



Integer variable :~ P$$$HPAD 
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P$ABORT 

P$ABORT calls P$OSDXP to abort the current job step. No parameters are 
required. 



PROCEDURE P$ ABORT; EXTERNAL; 
* 

P$ABORT 



P$BREAK 

P$BREAK is used with P$DBP to perform data breakpoint checking for Pascal 
programs. P$BREAK informs P$DBP of the address to be monitored. See the 
Pascal Reference Manual, CRI publication SR-0060 for a detailed 
description and examples of the use of data breakpoint checking. 



PROCEDURE P$BREAK (VAR V: INTEGER; ISVAR: BOOLEAN) ; EXTERNAL; 

V 

Integer variable := address; 
P$BREAK (integer variable, FALSE) 

P$CALLR 

P$CALLR returns the name of the current procedure's caller. No 
parameters are required. 



PROCEDURE P$CALLR (VAR CALLER: ALFA) ; EXTERNAL; 
* 

p$callr (at fa variable) 
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P$CBV 



P$CBV provides access to call-by-value routines from Pascal programs. It 
takes a procedural parameter describing the call-by-value routine to be 
called and an array parameter describing register contents to be in 
effect when the routine is called. P$CBV returns the register contents 
at the end of the call-by-value routine* 



TYPE REGISTER = (AREG, SREG) ; 

REGISTERS = ARRAY REGISTER, 0..7 OP INTEGER; 

VAR REGS: REGISTERS; 

PROCEDURE call-by-value-routine; EXTERNAL; 

PROCEDURE P$CBV (PROCEDURE P; VAR R: REGISTERS) ; EXTERNAL; 



REGS := desired contents of registers; 



P$CBV (call-by-value-routine, REGS) 



P$CONNEC 

P$CONNEC changes the COS filename (7-character maximum) to the alfa type 
variable specified by STR* The change becomes effective only after a 
call to P$RESET or P$REWRITE. 

P is the file variable; STR is the new name for the file. 



PROCEDURE P$CONNEC (VAR P 2 TEXT ; STR : ALFA ) ; EXTERNAL; 



P$CONNEC (file name, alfa string) 



P$CONNEC implements the Pascal procedure CONNECT. 
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P$DATE 



P$DATE calls P$OSDDT to obtain the current date in the form DD/MM/YY. An 
ALFA variable to receive the current date should be passed as a parameter. 



PROCEDURE P$DATE (VAR CURRDATE; ALFA); EXTERNAL; 



P$DATE (alfa variable) 



P$DBP 

Calls to P$DBP are generated by the Pascal compiler for modules compiled 
with the BP+ option, P$DBP checks the contents of the word registered 
with the P$BREAK routine. If they have changed since the last call to 
P$DBP, a breakpoint message is written to $OUT. P$CBV is callable from 
CAL only. See the Pascal Reference Manual, CRI publication SR-0060 for 
more information on data breakpoint checking. 



P$PEBUG 

P$DEBUG (call by value only) produces and prints the runtime post-mortem 
dump (pmd) and, depending on the value of SI, takes one of the following 
actions. 

SI < 0 Continues execution 

SI in (0..1000) Performs an ENDP macro (same as halt) 

SI > 1000 Aborts 

The Pascal-callable entry name is P$RTMSG. 



P$DISP 

P$DISP deallocates the storage area at the address indicated by the 
pointer variable. Since P$DISP performs the inverse operation of P$NEW, 
the word at PTR-1 must contain the same linkage information put there 
previously by procedure P$NEW. The pointer PTR must conform to the 
limits of the heap. 
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P$DISP attempts to meld the newly freed area with an already existing 
free area. Should no meld be possible , the routine inserts the area into 
the free chain in ascending address order. Storage acquired from the 
system by exceeding the minimum heap si2e is not returned to the system. 



PROCEDURE P$DISP ( PTR : POINTER) ; EXTERNAL; 



P$DISP (pointer variable) 



P$DISP implements the Pascal procedure DISPOSE, 



P$DIVMOD 

P$DIVMOD (call by value from CAL only) performs a single-precision 
integer divide and modulus, returning the quotient in register SI and the 
remainder in register S2, 

P$DIVMOD implements the Pascal procedure DIV. 



P$ENDP 

P$ENDP executes a normal program exit, Processing resumes with the next 
job control statement if reprieve processing is not enabled for normal 
job step termination. No parameters are required. 



PROCEDURE P$ENDP ; EXTERNAL ; 



P$ENDP 
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P$EOF 



P$EOF returns the end-of-file status for a Pascal text/record file. 



FUNCTION P$EOF (VAR F:FILE OF type) : BOOLEAN; EXTERNAL; 



Boolean variable : ^P$EOF (file name) 



P$EOF implements the Pascal procedure EOF. 



P$EOLN 

P$EOLN returns the end-of-line status for a Pascal text file, 



FUNCTION P$EOLN (VAR F:TEXT) : BOOLEAN ; EXTERNAL ; 



Boolean variable :=P$EOLN (file name) 



P$EOLN implements the Pascal procedure EOLN« 



P$GET 

P$GET reads a logical record from file F and then sets the corresponding 
status bits in the file variable to reflect the current file status 
before returning to the caller. 

For files randomly accessed, the file is pre-positioned. For TEXT files, 
P$GET calls P$OSDRC to fill the buffer. 

For the FILE OF type clause, P$GET calls P$OSDRW. The user's variable 
serves as the I/O buffer by the setting of the buffer address and length 
with the statement; 

USER VARIABLE FILE VARIABLE ; 



SR-0014 



8-6 



P$GET implements the Pascal procedure GET. 



PROCEDURE P$GET (VAR P:PILE OF type) ; EXTERNAL; 
PlGET (file variable) 



P$HALT 

P$HALT stops program execution and invokes the runtime routine P$ DEBUG, 
which provides a post-mortem dump. 

PROCEDURE P$HALT; EXTERNAL; 
P$HALT 

P$HALT implements the Pascal procedure HALT. 
P$JTIMB 

P$JTIME calls P$OSDJT to obtain the number of CPU seconds used by the 
job. No parameters are required. 



TYPE STRING = PACKED ARAAY (1.80) OF CHAR; 
FUNCTION P$JTIME: REAL; EXTERNAL; 

Real variable :» P$JTIME 
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P$LQGMSG 

P$I£GMSG writes a message of up to 80 characters to the logfile. The 
character string must be truncated by a 0 byte or be 80 characters long. 



TYPE STRING = PACKED ARRAY [1.80] OP CHAR; 
PROCEDURE P$LOGMSG (STR: STRING) ; EXTERNAL; 

* 

P$LOGMSG { % chavaeter string*) 



P$LSTREW 

P$LSTREW is an alternate entry point into P$REWRITE which rewrites a file 
without positioning it. 



PROCEDURE P$LSTREW (VAR F: TEXT) ; EXTERNAL; 

m 
a 

P$LSTREW (textfile) 



P$MEMRY 

P$MEMRY obtains information about the heap in which dynamic variables are 
allocated. It takes an integer parameter describing the aspect of the 
heap to be returned. 



FUNCTION P$MEMRY (REQUEST? INTEGER) ; INTEGER; EXTERNAL; 
* 

Integer variable := P$MEMRY (request code) 
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Request codes for P$MEMRY; 



Request Action 

1 QUERY SIZE OP HEAP 

2 QUERY HIGH WATER MARK 

3 QUERY LOW WATER MARK 

4 QUERY NUMBER OF ALLOCATED HEAP AREAS 

5 QUERY NUMBER OF TIMES HEAP HAS GROWN 

6 QUERY NUMBER OF TIMES HEAP HAS SHRUNK 

7 QUERY NAME OF LAST HEAP ROUTINE USED 

8 QUERY NAME OF LAST ROUTINE TO CALL A HEAP ROUTINE 

9 QUERY LAST HEAP ITEM ALLOCATED/DEALLOCATED/ETC, 

10 QUERY SIZE OF LARGEST FREE BLOCK 

11 QUERY AMOUNT HEAP CAN SHRINK 

12 QUERY AMOUNT HEAP CAN GROW 

13 QUERY HEAP F.W.A. 

14 QUERY HEAP L.W.A. 

15 QUERY NUMBER OF TIMES HPALLOC CALLED 

16 QUERY NUMBER OF TIMES HPDEALLC CALLED 

17 DO A HEAP SHRINK 

18 DO A HEAP INTEGRITY CHECK 

19 DUMP HEAP STATISTICS TO $OUT 

20 DUMP HEAP CONTROL WORDS TO $OUT(ALL BLKS) 

21 DUMP HEAP CONTROL WORDS TO $OUT (FREE BLKS VIA NEXT) 

22 DUMP HEAP CONTROL WORDS TO $OUT(FREE BLKS VIA LAST) 



P$MOD 

P$MOD (call by value from CAL only) returns the modulus in register SI. 
P$MOD implements the Pascal procedure MOD. 



P$NEW 

P$NEW allocates the storage area at the address indicated by the pointer 
variable. SIZE contains the number of words to be allocated. The 
contents of the word preceding the user area contains linkage information 
for use by the P$NEW and P$DISP routines. Upon completion of P$NEW, PTR 
contains the address of the allocated user area. This area is 
zero-filled by the P$NEW routine. 
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PROCEDURE P$NEW (VAR PTR: POINTER; SIZE: INTEGER) ; EXTERNAL; 
* 

P$NEW (pointer variable, integer variable) 
P$NEW implements the Pascal procedure NEW* 

P$OSDBS 

P$OSDBS is an operating system dependent routine that rewinds a dataset. 
It takes the DSP offset of the dataset to be rewound as a parameter. 



PROCEDURE P$OSDBS (DSP: INTEGER) ; EXTERNAL; 
* 

P$OSDBS (DSP offset of dataset) 



P$OSDDT 

P$OSDDT is an operating system dependent routine that returns the current 
date in the form DD/MM/YY. An ALFA variable to receive the current date 
should be passed as a parameter. 



PROCEDURE P$OSDDT (VAR CURRDATE; ALFA) ; EXTERNAL; 
« 
* 

P$OSDDT (alfa variable) 
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P$OSDEP 



P$OSDEP is an operating system dependent routine that opens a dataset for 
processing. It takes the dataset name as a parameter and returns a DSP 
offset (which is used to describe the dataset to the other P$0SDxx 
routines that perform I/O) ♦ 



FUNCTION P$OSDEP (DSN: ALFA) : INTEGER; EXTERNAL? 



Integer variable := P$OSDEP (' dataset name') 



P$OSDJT 

P$0SDJT is an operating system dependent routine that returns the number 
of CPU seconds used by the job* No parameters are required* 



FUNCTION P$OSDJT: REAL; EXTERNAL; 
* 

Real variable := P$OSDJT 



P$OSDLM 

P$OSDLM is an operating system dependent routine that writes a message to 
the logfile ($LOG) . The logf ile message is terminated by a 0 byte (ASCII 
NUL) or the 80th character, whichever comes first. 



TYPE STRING = PACKED ARRAY 1..80 OF CHAR; 
PROCEDURE P$OSDLM (STR: STRING) ; EXTERNAL; 



P$OSDLM ('character string') 
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P$OSDPR 



P$OSDPR is an operating system dependent routine that sets the prompt 
string for the interactive dataset $IN„ 



PROCEDURE P$OSDPR (PROMPT: ALFA) ; EXTERNAL; 



P$OSDPR (DSP offset of dataset, 'prompt string 1 ) 



P$OSDQI 

P$OSDQI is an operating system dependent routine that returns TRUE if the 
dataset whose DSP offset is passed as a parameter is an interactive 
dataset ♦ 



FUNCTION PfOSDQI (DSP: INTEGER) : BOOLEAN; EXTERNAL; 



Boolean variable := P$0SDQI (DSP offset of dataset) 



P$OSDRC 

P$OSDRC is an operating system dependent routine that reads a character 
record from a dataset into a buffer. The DSP offset of the dataset to be 
read, the address and length of the buffer, and an integer variable to 
receive the return code are passed as parameters. After the call to 
P$OSDRC, the return code variable indicates the dataset 's status as 
follows : 



Returned value 



0 Implies normal return; length of record is (- 
returned value) 
= 0 EOF, EOD # or null record 
= 1 Insufficient space in buffer 
= 2 Unrecoverable hardware error 
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CONST MAXBUFFER « buffer length? 

TYPE BUFFER = ARRAY 1.. MAXBUFFER OF CHAR; 

VAR BUF: BUFFER; 

PROCEDURE P$OSDRC (DSP: INTEGER; VAR BUF: BUFFER; 
BUFLENGTH: INTEGER; VAR RETURN INFO; INTEGER); EXTERNAL; 



P$OSDRC (DSP offset of dataset, BUF, MAXBUFFER, integer variable) 



P$OSDRP 

P$OSDRP is an operating system dependent routine that enables the job to 
perforin reprieve processing. It takes a procedural parameter describing 
the routine to receive control in the event of a reprieve, a buffer area 
to hold the exchange package, and a mask value selecting the types of 
errors to be reprieved as parameters. See the Macros and Opdefs 
Reference Manual, CRI publication SR-0012 for a description of allowable 
mask values* 



TYPE EXCHANGEPACKAGE = ARRAY 1..40 OF INTEGER; 
VAR EP: EXCHANGEPACKAGE; 
PROCEDURE reprieve routine; 

PROCEDURE P$OSDRP (PROCEDURE P; EP: EXCHANGEPACKAGE; 
MASK; INTEGER) ; 



P$OSDRP (reprieve routine, EP, mask) 



P$OSDRW 

P$OSDRW is an operating system dependent routine that reads a record from 
a dataset into a buffer. The DSP offset of the dataset to be read, the 
address and length of the buffer, and an integer variable to receive the 
dataset^ status are passed as parameters. The status codes returned by 
P$OSDRW are identical to those returned by P$OSDRC above. 
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CONST MAXBUFFER = buffer length; 

TYPE BUFFER = ARRAY 1. .MAXBUFFER OF INTEGER; 

VAR BUF: BUFFER; 

PROCEDURE P$OSDRW (DSP: INTEGER; VAR BUF: BUFFER; 
BUFLENGTH: INTEGER? VAR RETURNINFO: INTEGER); EXTERNAL; 



P$OSDRW (DSP offset of dataset, BUF, MAXBUFFER, integer 
variable) 



P$OSDTM 

P$OSDlM is an operating system dependent routine that returns the current 
date in the form HH:MM:SS. An ALFA variable to receive the current time 
should be passed as a parameter. 



PROCEDURE P$OSDTM (VAR CURRTIME : ALFA); EXTERNAL; 



P$OSDTM (a-ifa variable) 



P$OSDWC 

P$OSDWC is an operating system dependent routine that writes a character 
record to a dataset. It takes the DSP offset of the dataset and a 
buffer's address and length as parameters. 
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CONST MAXBUFFER = maximum buffer length; 
TYPE BUFFER = ARRAY 1, .MAXBUFFER OF CHAR; 
VAR BUF: BUFFER; 

PROCEDURE P$OSDWC (DSPs INTEGER? 
BUF: BUFFER; 

BUFLENGTH: INTEGER) ; EXTERNAL; 



P$OSDWC (DSP offset of dataset, BUF, number of characters in buffer) 



PSOSPWF 

PSOSDWF is an operating system dependent routine that writes an end of 
file mark to the dataset whose DSP offset is passed as a parameter. 



PROCEDURE P$OSDWF (DSP: INTEGER); EXTERNAL; 



P$OSDWF (DSP offset of dataset) 



P$OSDWR 

P$OSDWR is an operating system dependent routine that writes a record to 
a dataset. The DSP offset of the dataset and the buffer's address and 
length are passed as parameters* 
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CONST MAXBOFFER = length of buffer; 

TYPE BUFFER = ARRAY 1. •MAXBUFFER OF INTEGER; 

VAR BUF: BUFFER ; 

PROCEDURE P$OSDWR (DSP: INTEGER; 
BUF: BUFFER; 

BUFLENGTH: INTEGER) ; EXTERNAL; 



P$OSEHR (DSP offset of dataset, BUF, length of buffer) 



P$OSDXP 

P$OSDXP is an operating system dependent routine that either terminates 
the program normally or aborts the current job step, depending on whether 
its Boolean parameter is FALSE or TRUE, respectively. 



PROCEDURE P$OSDXP (DOABORT: BOOLEAN) ; EXTERNAL; 



P$OSDXP (TRUE or FALSE) 



P$PAGE 

P$PAGE writes a page-eject function to the file specified by F. 



PROCEDURE P$PAGE (VAR FiTEXTFILE) ; EXTERNAL; 



P$PAGE (file name) 



P$PAGE implements the Pascal procedure PAGE. 
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P$PUT 



P$PUT writes a logical record from the file specified by P and then sets 
the corresponding status bits in the file variable to reflect the current 
file status before returning to the caller. 

For files randomly accessed, the file is pre-positioned«, For TEXT files , 
P$PUT pads the line to the end of the current word with blanks and then 
calls P$OSDWC. 

For the FILE OF type clause, P$PUT calls P$OSDWR. 

PROCEDURE P$PUT (VAR F:FILE OF type) ; EXTERNAL; 

P$PUT (file variable) 
P$PUT implements the Pascal procedure PUT. 

P$RB 

P$RB reads a 1- to 5-character Boolean argument from the text file F. 
Leading blanks are ignored. Arguments can be upper or lower case. 



PROCEDURE P$RB (VAR F:TEXT;VAR BOOL: BOOLEAN) ; EXTERNAL; 

V 

F$RB (file name, Boolean argument) 



P$RCH 

P$RCH returns, right-justified, the next character in the file. File 

status functions P$EOF and PJlEOLN are set where applicable. If P$EOLN is 
set, the next record is read before return. 
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PROCEDURE P$RCH (VAR F:TEXT;VAR CH:CHAR) ; EXTERNAL; 
P$RCH (file variable, character variable) 



P$READ 

P$READ performs a call to the procedure P$GET and then moves the file 
buffer to a user variable. 



PROCEDURE P$READ (VAR F: TEXT; VAR X : USERVARI ABLE ) ; EXTERNAL; 
* 
* 

P$BEKD(file variable, variable) 



P$READLN 

P$READLN fills the user text file buffer with the next record in the file. 



PROCEDURE PSREADLN (VAR F:TEXT) ; EXTERNAL; 

« 

P$READLN {file variable) 
P$READLN implements the Pascal procedure READLN. 
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P$REPRV 



P$REPRV allows a program to trap certain runtime errors* The errors to 
be trapped are selected by the bit mask that is passed as a parameter. 
See the Macros and Opdefs Reference Manual , CRI publication SR-0012 for a 
description of allowable mask values* 



PROCEDURE P$REPRV (MASK: INTEGER) ; EXTERNAL? 



P$REPRV (mask selecting errors to be reprieved) 



P$RESET 

P$RESET resets the specified file. If the file is not open f P$OPEN is 
called to open the file for reading. 

Upon exit from P$RESET, the file pointer is positioned at the beginning 
of the file. P$RESET implements the Pascal procedure RESET. 



PROCEDURE P$RESET (VAR F:FILE OF type) ; EXTERNAL; 
P$RESET (file variable) 



P$REWRIT 

P$REWRIT resets the specified file. If the file is not open, P$OPEN is 
called to open the file for writing. 

Upon exit from P$REWRIT, the file pointer is positioned at the beginning 
of the file. 



SR-0014 



8-19 



I 



PROCEDURE P$REWRIT (VAR P:PILE OP type) ; EXTERNAL; 

P$REWRIT (file variable) 
P$REWRIT implements the Pascal procedure REWRITE. 

P$RF 

P$RF performs a character-string read and returns the next signed real 
number in the file. Preceding spaces and end-of-lines are skipped • 



PROCEDURE P$RF (VAR F: TEXT; VAR R:REAL) ; EXTERNAL; 

* 
« 

P$RP (file variable, real variable) 



P$RI 

P$RI returns the next signed integer in the file. The range of the 
integer read is limited to -MAXlNT<in tege r <MAXINT . 

Preceding spaces and end-of-lines are skipped. The character sequence 
read must conform to the proper signed-integer syntax. 



PROCEDURE P$RI (VAR F: TEXT; VAR INT : INTEGER) ; EXTERNAL ; 
» 

P$RI (file variable, integer variable) 
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P$ROUND 



P$ROUND (call by value from CAL only) returns in register SI the rounded 
value of the argument as an integer. P$ROUND implements the Pascal 
procedure ROUND. 



P$RSTR 

P$RSTR reads the number of characters specified by WIDTH and places them 
in the packed character string specified by STR. The first character is 
right-justified in the first word. If the length of the current line 
exceeds the character string, the file pointer is left in raid-record. If 
the current line is exhausted by the read/ left-over positions in the 
character string are blank-filled on the right and the function P$EOLN is 
set. 



PROCEDURE P$RSTR (VAR F : TEXT; STR: STRING ; WIDTH: INTEGER) ; EXTERNAL; 



P$RSTR (file variable, character string, integer variable) 



P$RTIME 

A call to P$RTIME is generated by the Pascal program at the end of a main 
program compiled with the BT+ option. It takes the statistics collected 
by P$TIMER and prints a timing report to $OUT. No parameters are 
required. 



PROCEDURE P$RTIME; EXTERNAL; 



P$RTIME 
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P$RTMSG 



P$RTMSG is the Pascal-callable entry name for the subprogram P$DEBUG. 
P$RTMSG produces and prints the runtime post-mortem dump (pmd) and, 
depending on the value of X, takes one of the following actions, 

X < 0 Continues execution 

X in (0..1000) Performs an ENDP macro (same as halt) 

X > 1000 Aborts 



PROCEDURE PfiRTMSG ( X : INTEGER) ; EXTERNAL ; 



P$RTMSG 



P$RUNTIM 

P$RUNTIM (call by value from CAL only) initializes the Pascal environment 
with the following procedures: 

1. Creates a heap of size Al + A2 words 

2. Allocates space for the stack from the heap 

3. Initializes P$$$HEAP structure 

4. Opens the input file and initializes the variable 

5. Opens the output file and initializes the variable 

The input and output files are not initialized if the address given for 
their variables is zero. P$RUNTIM initializes a fixed-extent stack. 
However, the heap is extendable to the memory limit. See procedures 
P$RESET and P$REWRIT for information on opening Pascal textfiles. See 
procedures P$NEW and P$DISP for information on using the Pascal heap. 

At the time of the call, the registers specified contain the following 
information. 

Al Heap size in words 

A2 Stack size in words 

A3 Address of input file variable 

A4 Address of output file variable 
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P$SFRAME 

P$SFRAME returns a pointer to the base of the stack frame of the 
calling procedure. No parameters are required. 



FUNCTION P$SFRAME: INTEGER; EXTERNAL; 

* 

Integer variable :« P$SFRAME 



P$TIME 

P$TIME calls P$OSDTM to obtain the current time in the form HH:MM:SS. An 
ALFA variable to receive the current time should be passed as a parameter. 



PROCEDURE P$TIME (VAR CURRTIME: ALFA) ; EXTERNAL; 
P$TIME (alfa variable) 



P$TIMER 

Calls to P$TIMER are generated by the Pascal compiler for modules 
compiled with the BT+ option. P$TIMER collects runtime statistics to be 
printed later by P$RTIME. P$TIMER is callable only from CAL. 

P$TRACE 

P$TRACE is called by P$R0MSG to produce a stack walkback. No parameters 
are necessary. 
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PROCEDURE PSTRACE; EXTERNAL ; 
P$TRACE 



P$TRUNC 

P$TRUNC (call by value from CAL only) truncates the value of the argument 
and returns the truncated value in register SI* P$TRUNC implements the 
Pascal procedure TRUNC. 

P$WB 

P$WB writes a Boolean argument to a text file* 



PROCEDURE P$WB (VAR F : TEXT ; BOOL : BOOLEAN ; W : INTEGER) ; EXTERNAL ; 
» 

P$WB (file variable, Boolean variable, integer width) 



P$WCH 

P$WCH writes the character that is right-justified in CH as the next 
character in the file. 



PROCEDURE P$WCH (VAR F : TEXT ; CH : CHAR) ; EXTERNAL; 
PITCH (file variable, character variable) 
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P$WEOF 

P$WEOP calls P$OSDWF to write an end of file mark on the textf ile passed 
as a parameter. 



PROCEDURE P$WEOF (VAR T: TEXT) ; EXTERNAL; 
P$WEOF (textf ile) 



P$WI 

P$WI writes the integer with the width specified by FIELDW, to the file. 



PROCEDURE P$WI (VAR F: TEXT; INT: INTEGER; FIELDW: INTEGER) ; EXTERNAL; 

9 

F$VlHfile variable, integer variable, integer width) 



P$WO 

P$WO writes the octal representation of an integer value to a textf ile. 
It takes a textf ile, an integer value , and the desired field width as 
parameters. 



PROCEDURE P$WO (VAR T: TEXT; IVAL # WIDTH: INTEGER) ; EXTERNAL; 
P$WO (textf ile, integer value, field width) 
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P$WRFIX 



P$WRFIX writes the real number to a Pascal text file according to the 
rules for fixed-point representations. 



PROCEDURE P$WRFIX (VAR F : TEXT ? E : REAL ; W , FR : INTEGER) ? EXTERNAL } 

P$WRFIX (file variable, real variable, integer width, 
integer fraction digits) 

P$WRFIX implements the Pascal fixed-point write procedure. 
P$WRFLT 

P$WRFLT writes the real number to a Pascal text file according to the 
rules for floating-point representations. 



PROCEDURE P$WRFLT ( VAR F : TEXT ? E : REAL ; W : INTEGER) ; EXTERNAL ? 
* 

P$WRFLT [file variable, real variable, integer width) 



P$WRITE 

P$WRITE moves the user variable to the file buffer and performs a call to 
the procedure P$PUT. 



PROCEDURE P$WRITE (VAR F : TEXT ?X:USERVAR I ABLE )? EXTERNAL; 
* 

P$WRITE (file variable, variable) 



P$WRITE implements the Pascal procedure WRITE. 
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P$WRITLN 



P$WRITLN causes a line to be written to the textfile passed as a 
parameter. P$WRITLN implements the standard Pascal procedure WRITELN, 



PROCEDURE P$WRITLN (VAR T: TEXT) ; EXTERNAL? 



P$WRITLN (textfile) 



P$WSTR 

P$WSTR writes the packed character string STRING to the file F. The 
first character is right- justified in the first word. The length and 
width of the character string are specified by LEN and FIELDW, 
respectively. 



PROCEDURE P$WSTR (VAR F, TEXT; STRING: CHARSTRING; LEN r WIDTH: 
INTEGER) ■ EXTERNAL? 



P$WSTR(F, STRING, LEN f FIELDW) 



P$WSTR implements the Pascal character string write procedure. 
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MULTITASKING SUBPROGRAMS 9 



Multitasking subprograms create and synchronize parallel tasks within 
programs. They are grouped in the following categories: 

• Task routines 

• Lock routines 

• Event routines 

• Utility routines 

For further information on using these subprograms in a multitasking 
environment, see the Multitasking User's Guide, CRI publication SN-0222. 



TASK ROUTINES 

Task routines handle tasks and task-related information. 



TSKSTART initiates a task. 
Call from FORTRAN: 



CALL TSKSTART (t ask- array , name [ ,list] ) 



task-array 

Task control array (described under subtitle task control 
array) used for this task. Word 1 must be set. word 3, if 
used, must also be set. On return, word 2 is set to a 
unique task identifier that must not be changed by the 
program ♦ 

name External entry point at which task execution begins. This 

name must be declared EXTERNAL in the program or subroutine 
making the call to TSKSTART. 
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NOTE 



CFT does not allow a program unit to use its own name 
in this parameter* 



list (optional parameter) 

List of arguments being passed to the new task when it is 
entered. This list can be of any length. See the 
Multitasking User's Guide, CRI publication SNM)222, for 
restrictions on arguments included in list* 

Call from CAL: 



CALL TSKSTART , (task-array name, A register, list) ,USE-A7 



task-array name 

Control array (described under subtitle task control array) 

A register 

An A register containing the parcel address of the routine 
to multitask 

list List of arguments passed to the new task. No limitations 

on the length of the list. 



Example : 

PROGRAM MULT I 

INTEGER TASK1ARY ( 3 ) f TASK2ARY ( 3 ) 
EXTERNAL PLLEL 
REAL DATA (40000) 

C 

C LOAD DATA ARRAY FROM SOME OUTSIDE SOURCE 
C * • • 

c 

C CREATE TASK TO EXECUTE FIRST HALF OF THE DATA 
TASK1ARY(1)=3 
TASK1ARY ( 3 ) = ' TASK 1' 

C 

CALL TSKSTART ( TASK1ARY , PLLEL / DATA ( 1 ) ,20000) 

C 

C CREATE TASK TO EXECUTE SECOND HALF OF THE DATA 
TASK2ARY(1)«=3 
TASK2ARY ( 3) = ' TASK 2' 
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c 

CALL TSKSTART (TASK2ARY, PLLEL , DATA (20001) ,20000) 
0 • • * 

END 



TSKWAIT waits for the indicated task to complete execution. 
Call from FORTRAN: 



call tskwait (task-array) 



task-array 

Task control array (described under subtitle task control 
array) 

Example : 

PROGRAM MULTI 

INTEGER TASK1ARY(3) ,TASK2ARY(3) 
EXTERNAL PLLEL 
REAL DATA (40000) 

C 

C LOAD DATA ARRAY FROM SOME OUTSIDE SOURCE 

C • • m 

C 

C CREATE TASK TO EXECUTE FIRST HALF OF THE DATA 
TASK1ARY(1)=3 
TASK1ARY ( 3) = ' TASK 1' 

C 

CALL TSKSTART (TASK1ARY, PLLEL, DATA(l) ,20000) 

C 

C CREATE TASK TO EXECUTE SECOND HALF OF THE DATA 
TASK2ARY(1)»3 
TASK2ARY ( 3) = * TASK 2* 

C 

CALL TSKSTART (TASK2ARY, PLLEL, DATA (20001) ,20000) 
0 * • • 

C NOW WAIT FOR BOTH TO FINISH 
CALL TSKWAIT (TASK1ARY) 
CALL TSKWAIT (TASK2ARY) 

C 

C AND PERFORM SOME POST-EXECUTION CLEANUP 
C ... 

END 
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In the above example , TSKSTART is called once for each of two tasks. As 
an alternative , the second TSKSTART could be replaced by a call to PLLEL 
and the TSKWAIT removed* This alternate approach reduces the overhead of 
the additional task but can make understanding the program structure more 
difficult* The two approaches produce the same results* 

TSKVALUE retrieves the user identifier (if any) specified in the task 
control array used to create the executing task* 

Call from FORTRAN: 



CALL TSKVALUE {return) 



return Integer value that was in word 3 of the task control array 
(described under subtitle task control array) when the 
calling task was created* A 0 is returned if the task 
control array length is less than 3 or if the task is the 
initial task* 



Example : 

SUBROUTINE PLLEL (DATA, SIZE) 
REAL DATA (SIZE) 

C 

C DETERMINE WHICH OUTPUT FILE TO USE 
CALL TSKVALUE (I VALUE) 

IF(IVALUE *EQ. 1 TASK I 1 )THEN 

IUNITN0«3 
ELSE IF { I VALUE *EQ. *TASK 2 1 )THEN 

IUNITN0=4 
ELSE 

STOP Error condition; do not continue* 

ENDIF 

C • • • 

END 



TSKTEST returns a value indicating whether the indicated task exists. 
Call from FORTRAN: 



return=TSKTEST {task-array) 



return A logical • TRUE • if the Indicated task exists. A logical 
• FALSE* if the task was never created or has completed 
execution* 
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task-away 

Task control array (described under subtitle tasl control 
array) 



NOTE 

TSKTEST must be declared LOGICAL in the calling module. 



TSKTUNE modifies tuning parameters within the library scheduler. Each 
parameter has a default setting within the library and can be modified at 
any time to another valid setting. 



NOTE 

This routine should not be used when multitasking on a 
CRAY-1 Computer System. 

Because of variability between and during runs, the 
effects of this routine are not measurable in a batch 
environment. 



Call from FORTRAN: 



CALL TSKTUNE (keyword^ * value^ , keyword2 ' value2 # • • • ) 



Each keyword is an ASCII character string. Each value is an integer. 
The parameters must be specified in pairs but the pairs can occur in any 
order. The following lists the legal keywords. For more information 
about using this routine, see the Multitasking User's Guide, CRI 
publication SN-0222. 

MAXCPU Maximum number of COS logical CPUs allowed for the job 

DBRELEAS Deadband for release of logical CPUs 

DBACTIVE Deadband for activation or acquisition of logical CPU 

HOLDTIME Number of clock periods to hold a CPU, waiting for tasks to 
become ready , before releasing it to the operating system 

SAMPLE Number of clock periods between checks of the ready queue 
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Example : 



CALL TSKTUNE( 'DBACTIVE* ,1, 'MAXCPU 1 ,2) 



TASK CONTROL ARRAY 

Each user-created task is represented by an integer task control array, 
constructed by the user program. At a minimum, the array must be two 
Cray words. A third word can be included. Following is the array 
structure: 

0 8 16 24 32 40 48 56 63 

LENGTH 
TASK ID 
TASK VALUE 



LENGTH Length of the array in Cray words. The length must be set 
to a value of 2 or 3, depending on the optional presence of 
the task value field. The user sets the length field 
before creating the task. 

TASK ID A task identifier assigned by the multitasking library when 
a task is created. This identifier is unique among active 
tasks within the job step. The multitasking library uses 
this field for task identification, but the task identifier 
is of limited use to user programs. 

TASK VALUE (optional field) 

Field that the user can set to any value before creating 
the task. If TASK VALUE is used, LENGTH must be set to a 
value of 3. The task value can be used for any purpose. 
Suggested values include a programmer generated task name 
or identifier or a pointer to a task local storage area. 
During execution, a task can retrieve this value with the 
TSKVALUE subroutine. 



Example : 

PROGRAM MULT I 
INTEGER TASKARY(3) 

C 

C SET TASKARY PARAMETERS 

TASKARY(1)=3 

TASKARY ( 3} = 'TASK 1' 
C ... 

END 
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TSKLIST lists the status of each existing task, telling whether each task 
is running, ready to run, or waiting. If the task is waiting, the 
address of the lock or event or the identifier of the task waited upon is 
reported. 

Call from FORTRAN: 



CALL TSKLIST (dn) 



dn Optional name or unit number of the dataset to receive the task 
status list* The default is $OUT. 



LOCK ROUTINES 

Lock routines protect critical regions of code and shared memory. 



LOCKASGN identifies an integer variable that the program intends to use 
as a lock. This subroutine must be called for each lock variable before 
its use with any of the other lock subroutines* 

Call from FORTRAN: 



CALL LOCKASGN (name I, value]) 



name Name of an integer variable to be used as a lock. The 

library stores an identifier into this variable. The 
variable should not be modified by the user. 

value The initial integer value of the lock variable. An 

identifier should be stored into the variable only if it 
contains the value. If value is not specified, an 
identifier is stored into the variable unconditionally. 

LOCKON sets a lock and returns control to the calling task. If the lock 
is already set, the task is suspended until the lock is cleared by 
another task and can be set by this one. In either case, the lock will 
have been set by the task when it next resumes execution of user code. 
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Call from FORTRAN: 



CALL LOCKON {name) 



name Name of an integer variable used as a lock, 

LOCKOFF clears a lock and returns control to the calling task. Clearing 
the lock allows one of the waiting tasks to resume execution, but this is 
transparent to the task calling LOCKOFF. 

Call from FORTRAN: 



CALL LOCKOFF (nam) 



name Name of an integer variable used as a lock. 

LOCKREL releases the identifier assigned to the lock. If the lock is set 
when LOCKREL is called, an error results. This subroutine detects some 
errors that arise when a task is waiting for a lock that will never be 
cleared. The lock variable can be reused following another call to 
LOCKASGN. 

Call from FORTRAN: 



CALL LOCKREL (name) 



name Name of an integer variable used as a lock. 

I/DCKTEST tests a lock to determine its state (locked or unlocked) . 
Unlike LOCKON, the task does not wait. A task using LOCKTEST must always 
test the return value before continuing. 

Call from FORTRAN: 



re turn- LOCKTES T (name) 



return A logical .TRUE, if the lock was originally in the locked 

state. A logical .FALSE, if the lock was originally in the 
unlocked state, but has now been set. 

name Name of an integer variable used as a lock. 
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NOTE 



LOCKTEST must be declared LOGICAL in the calling module. 



EVENT ROUTINES 

Event routines signal and synchronize between tasks . 



EVASGN identifies an integer variable that the program intends to use as 
an event. Before this routine can be used with any of the other event 
routines f it must be called for each event variable. 

Call from FORTRAN: 



CALL EVASGN (name [, value)) 



name Name of an integer variable to be used as an event. The 

library stores an identifier into this variable. The 
variable should not be modified by the user. 

value The initial integer value of the event variable. An 

identifier should be stored into the variable only if it 
contains the value. If value is not specified , an 
identifier is stored into the variable unconditionally. 

EVWAIT delays the calling task until the specified event is posted. If 
the event is already posted, the task resumes execution without waiting. 

Call from FORTRAN: 



CALL EVWAIT (name) 



name Name of an integer variable used as an event. 

EVPOST posts an event and returns control to the calling task. Posting 
the event allows any other tasks waiting on that event to resume 
execution, but this is transparent to the task calling EVPOST. 
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Call from FORTRAN: 



CALL EVPOST (name) 



name Name of an integer variable used as an event. 



EVCLEAR clears an event and returns control to the calling task. When 
the posting of a single event is required (a simple signal) , EVCLEAR 
should be called immediately after EVWAIT to note that the posting of the 
event has been detected. 

Call from FORTRAN: 



call evclear [name) 



name Name of an integer variable used as an event. 



EVREL releases the identifier assigned to the event. If tasks are 
currently waiting for this event to be posted, an error results. This 
subroutine detects erroneous uses of the event beyond the specified 
region. The event variable can be reused following another call to 
EVASGN. 

Call from FORTRAN: 



CALL EVREL {name) 



name Name of an integer variable used as an event. 



EVTEST tests an event to determine its posted state. 
Call from FORTRAN: 



return^EVTEST (name) 



return A logical .TRUE, if the event is posted. A logical .FALSE, 
if the event is not posted. 

name Name of an integer variable used as an event. 
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NOTE 



EVTEST must be declared logical in the calling module. 



UTILITY SUBPROGRAMS 

Utility subprograms are used by the user-callable multitasking 
subprograms to perform queue manipulation and task scheduling functions . 



$TIBCR% builds a task information block, and returns the address in SI. 
Call from CAL: 



CALLV $TIBCR% 



Entry: 

(SI) Address of the task information block for the parent task. 
Exit: 

(SI) Task identifier assigned to the new task. 



$TIBDE% deletes a task information block. No explicit arguments are 
required by this routine. However, it does use the current value of the 
top of stack pointer (B67) . The user should be careful not to destroy 
this value when calling this routine. 

Call from CAL: 



CALLV $TIBDE% 



$RDYTSK% readies a task for execution. 
Call from CAL: 



CALLV $RDYTSK% 
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Entry: 
(SI) 



Address of task information block of task to ready. 



NOTE 

On the CRAY X-MP system, this routine should be called 
with the TSKLK hardware semaphore set. This semaphore 
is cleared before the routine exits. 



$RDYQUE% readies a queue of tasks for execution. 
Call from CAL: 



CALLV $RDYQUE% 



Entry: 

(51) Address of task information block of first task to ready 

(52) Address of task information block of last task to ready 



NOTE 

On the CRAY X-MP system, this routine should be called 
with the TSKLK hardware semaphore set. This semaphore 
is cleared before the routine exits. 



$SUSTSK% suspends execution of the calling task. 
Call from CAL: 

CALLV $SUSTSK% 



Entry: 

(Si) Address of queue where task is to be placed. 
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NOTE 



On the CRAY X-MP system, this routine should be called 
with the TSKLK hardware semaphore set. This semaphore 
is cleared before the routine exits. 



$0£LTSK% deletes the calling task and activates any tasks waiting for its 
completion* 

Call from CAL: 

CALLV $DELTSK% 



$SCHED% schedules logical CPUs for user tasks. This routine is executed 
when a change in task status occurs. $SCHED% does not necessarily return 
to the calling routine. It resumes execution at the address specified in 
the task information block of the first task in the ready queue. 

Call from CAL: 



J $SCHED% 



Entry: 

(SI) Current logical CPU running the calling task. 
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APPENDIX SECTION 



ALGORITHMS 



A 



The following algorithms describe the routines in section 3, Common 
Mathematical Routines* Descriptions are arranged alphabetically by 
routine name. 



ACQS AND ACQSV 

Ar ceo sine and arcsine are related by: 

arccos(£) = x - arcsin(a;) 
2 

therefore, if arcsine is calculated, a final subtraction from */2 
furnishes the arccosine if desired. Moreover, only positive values of 
x need be considered since 

arcsin(-x) * -arcsin(x), 

1. Calculate a reduced argument, r, a multiplier, m, and an addend, 
c 9 depending on Xt 



X 




m 


a 


0 < i < sin (^6) 


X 


1 


0 


sin(*/6) < x <_ sin(*/3) 


T 2 (x) = 2x 2 - 1 


1/2 


jc/4 


sin(*/3) < x <_ sin(5*/12) 


T 4 (x) «8ar 4 - Bx 2 + 1 


1/4 


3*/8 


sin<5*/12) < x <_ 1 


✓l-x2 


-1 


V2 



2. Compute arcsin(r) using a rational function of the form 
rP(r 2 )/Q(r 2 ) 

where P and Q are polynomials of degree 4 in r 2 . 
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3* Multiply the result by m and add a. 

4. Insert the result sign, which is the sign of x. 

ALOG AND ALOGV 

The common and natural logarithms are related by 
log (x) « log e • In x 

therefore, if the natural logarithm is calculated, a final multiplication 
by log e furnishes the common logarithm, if desired* 

1. Express the argument, x, as 2 n f where 1/}ST <_ f < /2. Then 

ln(x) = ln(2 n /) = log 2 2* • In 2 + In {/) - nln 2 + ln(/) 

To determine n and f, observe that x is represented in floating-point 
format as x = 2 c where 1/2 <_e < 1. When 1/2 <_ a < 1^2, then 1 <_ 2c < 
In this case, \n{x) « ln(2^) * ln[2^ 1 (2<?)] » (ZKL)ln 2 + In (2c) 
so that w = fc-1 and 2c?. When ± o < 1, we have t? » 2> and / = c. 

2. Compute * * (/ - l)/(/ + 1) . 

3. Compute ln(f) using a rational function of the form 

2t - tP(t 2 )/Q(t 2 ) 
where P and Q are polynomials of degree 3 in t 2 . 

4. Multiply the exponent n by In 2 and add to the result, 

5. If the common logarithm is desired, multiply by log 

ATAN AND ATANV 

1. Let 2 = \x\ m if s > 1, replace 2 with l/s 

2. Compute the integer n - [16a] . Let t - n/16* 

3. Compute w = (3 -*)/(! + ts) 
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4. Compute arctan(w) using a polynomial P(w} of degree 9, 

5. Let a s 0 if z f_ 1 and a « */4 if js > 1. 

6. Let e = arctan(t). 

7. Form arctan (3) - (a - e) + c - P(w) . 

8. Insert the result sign depending on the magnitude of z, the sign of 
x and the sign of arctan (3). 

A TAN 2 AND ATAN2V 

Use the same algorithm as $ATAN and $ATANV. 
CABS AND CABSV 

The complex absolute value of z - x + iy is defined by the 
following equation. 

\z\ = Vx* + 

1. Compute w = min ( I x| r \y\) and v ~ max (|x| f | y\ ) m 

2. If v = 0, return with I si =0. 

3- If V f 0, express \z\ as v Vl + (u/v) 2 = v fw~ where w lies in the 
interval [l f 2]. This expression avoids possible overflow in the 
computation x 2 + z/ 2 . 

4, Compute an initial approximation to as 

a 0 = 33/32 + 3/8 (w - 33/32) • 

5, Apply the Newton-Raphson iteration three times to compute /tJ7 

« 1/2 (a n + w/a n ) 
three times to compute ifwl 

6, Multiply by v to obtain the final result. 
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CCOS AND CCOSV 

The complex cosine of z 53 x + iy is defined by 

cos (2) = cos (a:) cosh ( 2/) + sin(x) sinh(y) 

1. Call COSS% to compute cos(x) and sin(x) • 

2. Call COSSH% to compute cosh<#) and sinh(#). 

3. Multiply cos(x) by cosh(z/) to obtain the real part of cos (3). 

4. Multiply sin (a:) by sinh(z/) to obtain the imaginary part of 
cos (3) . 

CEXP AND CEXPV 

The complex exponential of z = x + iy is defined by 
e z « eP cos(j/) + ie x sin(z/). 

1. Call EXP% to compute e x . 

2. Call COSS% to compute cos (y) and sin(z/>. 

3. Multiply e x by cos(y) to obtain the real part of e z . 

4* Multiply e x by sin(z/) to obtain the imaginary part of e z . 

CIX)G AND CLOGV 

The complex logarithm of z ~ x + iy is defined by 
log<s) = ln|s| + i arctan{#/a;) . 

1. Call ATAN2% to compute arctan {y/x) which is the imaginary part of 
log (s) . 

2. Call CABS% to compute |sK 

3. Call ALOG% to compute ln|s| which is the real part of log (3). 
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COS AND COSV; COSS AND COSSV 

1. Compute n = [4/x \x\J which is the number of multiples of -V4 in |x|. 

2. Define m « n mod 8. 

3. Define a * 1 if computing cosine? else (2=0. 

b = Low-order bit of w 
c = Middle bit of m 
d = High-order bit of /n 
e = Argument sign 

4. Compute the reduced argument / = | x| - */4(n + 6) in double-precision, 

5. Define t = a\i?\p. f 

6. Compute sin(f) if t = 0 and cos(/) if t = 1 using 
approximations of degree 6 in f 2 . 

7. Insert the result sign which is [#a&(<A^)l I [a&(d\c)]. f 
COSH AND COSHV 

1# Compute the integer n nearest to |x|/ln 2. £ = ??ln 2 + / where 

\f\ < . 

~~~ 2 

2. Approximate cosh(/) - 1 using a polynomial P(f 2 ) of degree 5 in f 2 . 

3. Approximate sinh(/) using a rational function of the form 

P(f) = / 2 d/2 + f 2 (P 4 + f 2 (P 6 + f 2 ) <P 8 + f 2 ) P 10 ))) 

4. If cosh(x) is desired, use the following formula 

cosh(x) = [1 + (P - e)]2-^" 1 + [1 + (P + 0]2*-l 
where P = cosh(/) - 1 and Q = sinh(/). Observe that since 

x nln 2 + f In 2 w f „n f 
f \= Logical difference; #scomplement? & = AND; I —OR. 
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we have 

cosh(x) « * X + & ~ X _ 2V 4- 2~ n e~? _ 2 n-i e f 2 -«-l e -/ 
2 2 ~ 

<^ + g"-^ _ - j 2 -r *-l + f + *"/ + - e"/ j 2 n-l 
2 2 y y 2 2 

* (cosh(/J - sinh(/)) 2 - "" 1 + <cosh(/) + sinh{/))2 w - 1 

= [1 + (cosh(f)-l) - sinh(/)]2~ M ~ 1 + [1 + (cosh(/) - 1) + 
sinh{/)]2" -1 

= tl + {P - Q)]2~ n ~ 1 + [1 + <P + Q)]2 n ~ 1 . 

5. If sinh(ar) is desired, return with sinh(ar) = sinh(/) if rt=0. 
When n / 0, use the formula 

sinh(rc) - 2 n ~ 3 + (2 n ~ 3 - [1 + (P - «)] 2" n_1 ) + [2" 1 + (P + 0J2"" 1 
where P = cosh(/) - 1 and Q = sinh(/). Observe that since 

e * m n In 2 + / . e ln2 nf = 2 
we have 



sinh(x) ^ # 



2 n ef - 2~ M "/ m 2 rt-l e f _ 2 -^l^/ 



= (cosh(/) + sinh(/>)2* -1 - (cosh(/) - sinh{/) ) 2~ n ~ 1 

= 11+ (cosh{/) - 1) + sinh(f)]2"- 1 - [1 + (cosh(/)-l) 
- sinh(/)]2" n " 1 

= II + (P + Q)]2 11 ~ 1 - [1 + (P - 3JJ2"""" 1 

= [2' 1 + (P + 0J2"" 1 - [1 + (P - 0 ] 2 - "" 1 + 2 M " 3 + 2"* 3 

» 2*~ 3 + (2*~ 3 - [1 + (P - ^)]2" n " 1 ) + [2 -1 + (P + ^)]2 ?1 " 1 
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COT AND COTV 

1. Compute n « L 4 /*I#IJ# which is the number of multiples of */4 in 

2. Define m = n mod 8, 

3. Define a = 1 if computing cotangent; else, a=0. 

b « Low-order bit of m 
<3 = High-order bit of m 
d = Argument sign 

4. Compute the reduced argument / - |x| - K /A{n + 6) in double-precision, 

5. Define t = c\^\e. f 

6. Compute tan(/) using a rational function of the form 

fP(f 2 )/Q(f 2 ) 

where P and Q are polynomials of degree 3 in / 2 . 

7. If t - 1, replace the result with its reciprocal* 

8. Insert the result sign, which is c\d. f 



CSIN AND CSINV 

The complex sine of z = x + iy is defined by 

sin (s) « sin(x) cosh(y) + icos(x) sinh(y). 
1. Call COSS% to compute cos(x) and sin(x). 
2» Call COSSH% to compute cosh(#) and sinh(a}. 

3. Multiply sin(x) by cosh(z/) to obtain the real part of sin (2) . 

4. Multiply cos(x) by sinh(#) to obtain the imaginary part of sin(s). 



t \= Logical difference 
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CSQRT AND CSQRTV 

The complex square root of z = x + iy is defined by 

lfz~ Vl/2(\z\ + x) ± i Vl/2(\zl - x) = u + ty 

where 2uz> = y and where the ambiguous sign is taken to be the same as the 
sign of y. 

1. If 3 = 0, return with 0 as the answer. 

2. Call CABS% to compute 

3. Compute c * J g > + l x| 

4* Call SQRT% to compute u = 

5. Compute v = Ij/J, 

2u 

6. If x < 0, swap u and y. 

7. Insert the imaginary result sign, which is the sign of y. 



CTOCSS, CTOCSV, CTOCVS, AND CTOCW 

Exponentiation of a complex number z = x + iy is defined by 

z a _ ln{s) * exp(alnU) + iarctan(s)) 

= exp[(wln|s| - yarctan y/x ) + i(uarctan y/x + uln|»|)J 

s t 

= e 8 (cos(*) + isin(t)) 

where a = u + iy. 

Other library routines are called according to the above definition to 
compute the result. 
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CTOISS, CTOISV, CTOIVS, AND CTOIW 

1. Return 0 if the base is 0 and the exponent is greater then 0. 

2. Return (l r 0) if the base is nonzero and the exponent is 0. 

3. Compute the absolute value of the exponent e. Write \e\ as 

e 2 n + e - + . . . + <2, 2 + e 
n rt-1 1 0 

where is either 0 or 1. 

4. Form jt S 

5. Take the reciprocal if the exponent is negative and return. 
CTORSS, CTORSV, CTORVS, AND CTORW 

Exponentiation of a complex number z « x + iy is defined by 
z n se nln\z\ [ COS ( narc tan(#/x) ) + £sin(narctan(z//tf) ) ] 
1* Return 0 if the base is 0 and the exponent is nonzero. 

2. Return (1,0) if the base is nonzero and the exponent is 0. 

3. Call other library routines according to the above definition to 
compute the result. 

DACOS AND DACOSV 

Compute using the identity 

arccos{x) = arctan( l-x 2 ) 

x 
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DASIN AND DASINV 

Compute using the identity 

arcsin(x) = arctan (ar/fl - x^) 



DATAN AND DATANV 

The subroutine computes the double -precis ion arctangent of y/x. An 
alternate 1 -argument entry point is provided with x assigned the value 1. 

1. If x = 0 r return with sin(y) * K /2 as the result* 

2. If y/x <_ 2~ 17 , compute the arctangent using the first two terms of 
its Taylor series. 

3. Define q - \y/x\ 9 a * tan( */16) and b « tan{3 */16) • 
4* Select v and e depending on q. 



<7 


r 


0 


0 <^q < tan{*/8) 


(q - a)/(l + c?a) 


*/16 


tan{*/8) ±q < 1) 


(<? - b)/(l + qi) 


3*/16 


i z. q < 


(1 - qb)/{q + 2)) 


5*/16 


<_ q <•» 


(1 - qa)/(q + a) 


7*/16 



5. Compute arctan (r) using the polynomial of degree 27 obtained by 
economizing the power series of degree 39. 

6. Add e to the result to obtain arctan (q) . 

7. Insert the result sign, which is the logical difference of the signs 
of y and x* 
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DCOS AND DCOSV 



1. Compute the integer n nearest to x * 2/jc • 

2. Compute the reduced argument y = x - n* */2 which lies in the 
interval (- */4, */4) . 

3. Define a = 1 if computing cosine; else a = 0. 

4. Compute cos (y) if n + a is odd and sin(#) if n + a is even. Use the 
polynomial obtained by economizing the first 13 terms of the Taylor 
series to 11 terms. 

5. Insert the result sign, which is the sign of w + a - 1. 

DCQSH AND DCOSHV 

Compute using the identity 

cosh(x) = e x + e~ x 
2 

DCOT AND DCOTV 

Compute using the identity 

cot(r) = cos (r) /sin {x) 

DEXP AND DEXPV 

1. Compute the integer n nearest to a?log 2 5« 

2. Compute the reduced argument w = x - rzln 2. 

3. Compute e x using the polynomial of degree 17 obtained by economizing 
the power series of degree 20* 

4. Add n to the exponent to obtain the final result. 
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DLOG AND DLOGV 

1. Express x as 2 n f where 1/V2 <J< Vl+ Then 

ln(x) = ln(2 n f) = log 2 2* • In 2 + ln(/) = nln 2 + lnff) . 

2* For a first approximation a§ to ln(/) # use a polynomial of degree 7 
in 3 - / - 1/f + !♦ 

3* Apply the Newton-Raphson iteration 

a n+1 = - £<£»!_- « n - % - (1 - f 0 ") 

<?'(a n ) 0 « 

two times to compute ln(/). a 2 is computed directly from a Q using 
the formula 

a 2 « [ <a 0 - * M ) - tj.] - t M 2 ( l + 

2 3 

The formula is derived by neglecting terms that are insignificant. 

Let r=fe~ a Q and t=l-i*=t u +ti where t u is the most significant part of t 
and is the least significant. Then 



a 2 = ax - (1 - = fll - [l - /<T (£2 0 " 



= a x _ (1 - fe~ a °e tu ) = a x - (1 - re*") = a 0 - t M - {1 - re* M ) 

ignoring the least significant part of t. 

t 

Expanding e u as a power series truncated to four terms, we have 



t t 2 t 3 

a 0 - t M - (1 - v* u ) &a 0 - t u - [1 - r(l + t u + + I" )] 

« a 0 - *« - U - r - r* M - i|*f - 



»«0 - *u - f*u + H - <* M - t 2 ) - - ■![£-) -1 



t 2 t 3 

*«o - *u - n - - \ 

*(«0 - *> " *U 2 <| + % 
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Note that in the derivation above, some terms have been ignored. 
1 - r - t u + t t « v = 1 - t u - t t 

rt u = (1 - t u - ti)t M = t u - t M 2 - t^ M t u - t u 2 

2 2 2 2 ~72 2 IT 

6 6 6 ~ 76 6 

4. Multiply the exponent n by In 2 and add to the result* 

5. If the common logarithm is desired , multiply by log e. 



DMQD AND DMODV 

1. Divide x by y and extract the integer part n. 

2. Return with x - ny as the result. 



DSINH AND DSINHV 

Compute using the identity 

sinh(ar) m e x - e~ x 



DSQRT AND DSQRTV 

1. Call SQRT% to compute an initial approximation , y Q . 

2. Perform one Newton-Raphson iteration to yield the double-precision 
result. 

2 #0 
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DTAN AND DTANV 

Compute using the identity 

tan(x) = sin (x) /cos {x) 

DTANH AND DTANHV 

Compute using the identity 

tanh(x) = sinh (x)/cosh(x) 

For x = 0, return (tanh(0) ** 0) 

For x < 0, tanh(x) *= (e 2x - l.)/(e 2x + 1.) 

For x > 0, tanh(x) - (l.-e~ 2x ) /{ <T 2x + 1.) 

DTODSS , DTODSV, DTODVS, AND DTODW 

1. Return 0 if base = 0 and exponent > 0. 

2. Call DLOG% to compute logarithm of base. 

3. Call DMSS% to multiply logarithm of base by exponent. 

4. Call DEXP% to compute final result. 

DTOISS, DTOISV, DTOIVS, AND DTOIW 

1. See the algorithm for $RTOISS, $RTOISV, $RTOIVS, and $RTOIW. 

2. The series of multiplies is done by successive calls to DMSS%, 

3. If base = 0, exponent must be > 0. 

EXP AND EXPV 

1. Multiply x by 2/ln 2 and write 

y « x • 2/ln 2 « 2n^ + + / 
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where n± and rz 2 are integers, 0 <^ n 2 < 2 and 0 <_ f < 1. Observe that 
x m e (x/ln 2) (In 2) = ( ^ln 2 } x / ln 2 = 2 x/ln 2 

= 2 («i + V 2 + // 2 > a 2 rZ l2 n2/2 2 //2 , 

2. Extract the integer and fractional parts of z/. The least significant 
bit of the integer part is ny and the remaining bits are ?i 2 . The 
fractional part is /. 

3. Compute using a rational function of the form 

Qix 2 -) + xP(x 2 ) 
Q(x 2 ) - xP(x 2 ) 

where P and Q are polynomials of degree 2 in a; 2 , Let x = f/2. 

4. Multiply 2<f /2 by ^2 if n 2 is 1. 

5. Add n± to the exponent of the result. 

ITOISS 

1. If base i * 2 and exponent j _> 0, calculate result t = 2<? and 
return. Otherwise, calculate ABS(i) as the initial product, 

2. Using ABS(j) as an index, read the section of the multiplication tree 
that gives the path of the minimum number of multiplications 
necessary for this exponent* 

3* Calculate intermediate products until the path is exhausted. 

4. If i < 0 and j (modulo 2) f 0, negate final product to obtain the 
result. Otherwise, return the final product as the result, 

ITOIVS, ITOIW 

1. See the algorithm for RTOISS, RTOIVS, RTOIW. 

2, The series of multiplies are done as 64-bit integer multiplication. 
3* If base i » 0, exponent j must be greater than 0, 
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RANF 



Let <S(n)> be the linear congruential sequence produced by setting 

s n+l m v&n mod 2 48 ' "ill- 
Select a suitable multiplier m and starting seed Sq* Use 5 n , n > 0, as 
the coefficient for the n^* 1 random number. Use 40000 as the biased octal 
exponent and normalize the result to obtain random numbers in the range 
(0, 1) . Since (i mod N) (j mod N) « ij mod N for integers the 
result is 

5 ?i+64 - m 6A S n mod 2 48 

enabling computation of 64 seeds at a time using vector instructions and 
64 initial values S^, 1 < i < 64. Care must be taken to allow 
intermixing of scalar and vector RANF calls. The algorithm follows. 

1. If only 64 random seeds remain in the 128-word buffer, go to step 4. 
Otherwise, read the next seed and increment the buffer index. 

2. Use the seed as the coefficient and 40000g as the biased exponent to 
create the unnormalized random number. 

3. Normalize the random number and return. 

4. Move the 64 remaining seeds from the second half of the buffer to the 
first half. 

5. Apply the multiplicative congruential method to generate the next 64 
seeds and store them in the second half of the buffer. 

6. Reset the buffer index to point to the second seed in the buffer. 

7. Use the first seed in the buffer as the coefficient and use 40000 8 as 
the biased exponent to create the unnormalized random number. 

8. Normalize the random number and return. 



RANFV 

Refer to the description for RANF for additional detail. 

1. Read the next VL seeds from the buffer. 

2. Use the seeds as the coefficients and use 40000g as the unbiased 
exponent to create the unnormalized random numbers. 

3. Normalize the random numbers. 
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4. Compute VL and increment the buffer index by that amount* 

5. Return if 64 or more seeds remain in the buffer, 

6. Move the 64 newest seeds from the second half of the buffer to the 
first half and decrement the buffer index by 64* 

7. Apply the multiplicative congruential method to generate the next 64 
seeds and store them in the second half of the buffer • 

8. Restore VL to its original value and return, 
RANGET 

Return the current seed as a 64-bit integer. The random number generator 
can be reset at some later time to the current state by calling $RANSET 
with the 64-bit integer as an argument, 

RANSET 

1. Use the default seed if the supplied seed is 0, Otherwise, take the 
seed modulo 2 48 and make it odd to prevent zero propagation, 

2. Apply the multiplicative congruential method to generate the first 
128 seeds to fill the buffer. 

3. Clear the buffer index and return. 

RTOISS, RTOIVS , AND RTOIW 

1. If exponent e < 0 r compute base z = i/s. 

2. Compute the absolute value of the exponent £. Write I e\ as 

e n 2 n + en-\Z n ~ X + ... e±2 + e Q 

where is either 0 or 1. 

3. Form * z^ 

H* 1 
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RTORSS 

1. Return 0 if the base is 0 and the exponent is greater than 0. 

2. Return 1 if the base is nonzero but the exponent is 0. 

3. Call ALOG% to compute the logarithm of the base, 

4. Multiply by the exponent. 

5. Call EXP% to compute the final result and return. 
RTQRVS 

1. Return 0 if the base is 0 and the exponent is greater than 0. 

2. Return 1 if the base is nonzero but the exponent is 0. 

3. Call %ALOG% to compute the logarithm of the base. 

4. Multiply by the exponent. 

5. Call %EXP% to compute the final result. 

RTORW 

1. Call %ALOG% to compute the logarithm of the base. 

2. Multiply by the exponent. 

3. Call %EXP% to compute the final result. Return 0 for any zero base 
if the exponent is greater than 0. 
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SQRT AND SQRTV 

This algorithm was designed and implemented by Harry K. Nelson , Lawrence 
Livermore Laboratories. 

!• If x = 0, return yST - 0. 

2. Compute an initial approximation J/ 0 /16 accurate to 17% as a function 
of x/2048. 

3. Using a half-precision divide approximation, compute three 
Newton-Raphson iterations of the form 



2 A-n \ 2 4-(n-l) \ yn _ x J 2 4-(n-l) • 2 4-<n-l) ) 

4* Using a full-precision divide approximation, compute a final 
Newton-Raphson iteration yielding 




TANK AND TANHV 

1. If x 17.3287, return with tanh(tf) » + 1 where the sign of the result 
is the sign of x* 

2. If \x\ < 0.12, approximate tanh(ar) using the first six terms of the 
power series. 

Of 

3. For all other values of x, call EXP% to compute e . 
4* Return with tanh{x) = 1 - 2/1 + e 2x . 
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PERFORMANCE STATISTICS 



B 



This section contains accuracy and timing statistics for the 
single-precision, single-argument routines listed in section 3, Common 
Mathematical Subprograms, and for $SCILIB routines listed in section 4, 
Scientific Applications Subprograms. 

The figures listed in table B-l are for a CRAY-1 S Series Computer System 
with 8-bank memory* The CRAY-1 S computer with 16-bank memory does not 
typically show a significant difference in performance; however, for 
these routines, the performance is three to seven percent faster. 



COMMON MATHEMATICAL SUBPROGRAMS 

These statistics are arranged alphabetically according to entry names of 
the subprograms. Listed in table B-l are the following column headings: 

Entry name - the entry name that must be used to call the subprogram 

Domain - the domain used to obtain the accuracy figures. For each 
function, accuracy figures are given for one or more representative 
segments within the valid domain. In each case, the figures given are 
the most meaningful to the function and domain under consideration. 

Ten thousand arguments are selected for each domain. The arguments are 
uniformly distributed unless otherwise noted. 

Accuracy - accuracy figures (maximum relative error and standard 
deviation) for one or more representative segments within the valid 
domain. The accuracy figures supplied are based on the assumption that 
the arguments are perfect (that is, without error and, therefore, having 
no error propagation effect upon the answers) ♦ The only error in the 
answers are those introduced by the subroutines. 

Average result rate (usec/result) - timing statistics. Values 
represent the average result rate in microseconds for scalar computations 
and for vector computations using vector lengths of 1, 2, 4, 10, 32, and 
64 elements. All timing information was gathered with interrupts 
disabled. 
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Table B-l. Statistics for s ingle-precision , single-argument 
subprograms 



Accuracy Average Result Rate ( x Sees/Result) 



Entry 


Domain 


Max* 
Error 
(xlO 14 ) 


Stdrd 
Dev 

(xlO ") 


Scalar 




Vector 


Length 




1 


2 


4 


10 


32 


64 


ACOS% 


("lr 1) 


2.910 


4.233 


2.2 


3.8 


2.0 


1.0 


0.5 


0.3 


0.2 




(0. 1) 

\ V , x / 


2.134 


3.388 


2.2 


3.9 


2.0 


1.0 


0.5 


0.3 


0.2 




(0, 1/2) 


0.944 


2.695 


2.0 


3.5 


1.8 


0.9 


0.4 


0.2 


0.2 




(1/2, sin */3) 


1.064 


3.150 


2.2 


3.9 


2.0 


1.0 


0.5 


0.3 


0.2 




(sin */3, sin5 */12) 


2.469 


5.635 


2.5 


4.5 


2.3 


1.2 


0.6 


0.3 


0.3 




(sin5 */12, 1) 


2.134 


4.564 


4.2 


7.3 


3.7 


2.0 


0.9 


0.5 


0.4 


ALOG% 


(1/2, 2} 


1.639 


3.886 


2.0 


3.0 


1.5 


0.8 


0.4 


0.3 


0.2 


%ALOG% 


(0,oo )f 


1.562 


4.282 


2.0 


2.9 


1.5 


0.8 


0.4 


0.3 


0.2 


ALOG10% 


(1/2 , 2) 


1.500 


4.077 


1.9 


3.2 


1.7 


0.9 


0.4 


0.3 


0*2 


%ALOG10% 


(0, oo )t 


1.786 


3.924 


1.9 


3.2 


1.6 


0.9 


0.4 


0.3 


0.2 


ASIN% 


(-1, 1) 


1.765 


3.888 


2.2 


3.7 


1.9 


1.0 


0.5 


0.3 


0.2 


%ASIN% 


(0, 1) 


1.655 


3.874 


2.0 


3.7 


1.9 


1.0 


0.5 


0.3 


0.2 




(0, 1/2) 


1.985 


4*008 


1.8 


3.3 


1.7 


0.9 


0.4 


0.2 


0.2 




(1/2, sin V3) 


1.189 


3.093 


2.0 


3.8 


1.9 


1.0 


0.5 


0.3 


0.2 




(sin V3, sin5 */12) 


1.349 


5.594 


2.2 


4.3 


2.2 


1.2 


0.6 


0.3 


0.3 




(sin5 */12, 1) 


0.578 


2.152 


3.9 


6.9 


3.5 


1.9 


0.9 


0.5 


0.4 


ATAN% 


(- */2, */2) 


1.057 


3.549 


1.7 


4.1 


2.1 


1.1 


0.6 


0.3 


0.2 


%ATAN% 






















COS% 


(- V4, */4) 


0.474 


1.656 


1.9 


4.0 


2.1 


1.1 


0.6 


0.3 


0.3 


%COS% 


(- * ) 


1.010 


2.312 


2.1 


4.0 


2.1 


1.1 


0.6 


0.3 


0.3 




(-100, 100) 


50.043 


16.824 


2.1 


4.0 


2.1 


1.1 


0.6 


0.3 


0.3 


cosa% 


(-0,301, 0.301) 


0.712 


3.177 


2.1 


3.6 


1.8 


1.0 


0.5 


0.3 


0.3 


%COSH% 


(-5677, 5677) 


1.319 


3.980 


2.1 


3.6 


1.8 


1.0 


0.5 


0.3 


0.3 


COT% 


(- V4, */4) 


1.835 


5.058 


2.3 


3.4 


1.7 


0.9 


0.5 


0.3 


0.2 


%COT% 


(-100, 100) 


60.847 


24.833 


2.3 


3.4 


1.7 


0.9 


0.5 


0.3 


0.2 



t Samples are exponentially distributed. 
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Table B-l. Statistics for single-precision , single-argument 
subprograms (continued) 



Entry 


Domain 


Accuracy 


Average Result Rate ( n Sees/Result) 


Max* 
Error 
(xl0~ 14 ) 


Stdrd 
Dev 

(xlO" 15 ) 


Scalar 




Vector 


Length 




X 


2 


4 


10 


32 


64 


EXP% 


(-1, 1) 


2,170 


7.482 


1*6 


2.5 


1.3 


0.7 


0.3 


0.2 


0.2 




\ 3D / / , Daft/ 


2.045 


7.408 


1.6 


2.5 


1.3 


0.7 


0.3 


0.2 


0*2 


SIN% 


(- */4, */4) 


0.698 


2.244 


1.8 


3.9 


2.0 


1*1 


0.5 


0.3 


0.3 


ft CTMft 

win? 




0.927 


2*108 


1.9 


3.8 


2.0 


1.1 


0*5 


0.3 


0.3 




(-100, 100) 


20*809 


8.512 


2.0 


3*8 


2.0 


1.1 


0.5 


0.3 


0.3 






ft CO £ 


2.273 


2.3 


4.0 


2.1 


1.1 


0*6 


0.4 


0.3 


%SINH% 


(-5677, 5677) 


1.032 


3.974 


2.2 


4.0 


2.1 


1*1 


0*6 


0*4 


0.3 


SQRT% 


(0, 1) 


0*767 


1.931 


1.5 


2.3 


1.2 


0*6 


0.3 


0*1 


0.1 


%SQHT% 


(0,oo )t 


0.724 


2.099 


1.5 


2.3 


1.2 


0.6 


0.3 


0.1 


0.1 


TAN% 


(- */ 4 , */4) 


1*444 


4.274 


1*8 


3.4 


1.8 


0.9 


0.5 


0.3 


0.2 


%TAK% 


(-100, 100} 


60*456 


24.830 


2.1 


3.4 


1.8 


0.9 


0.5 


0.3 


0.2 


TANH% 


(-20, 20) 


5.671 


5.822 


2.8 


4.6 


2.4 


1.2 


0*6 


0.3 


0.3 


%TANH% 


(-1/2, 1/2) 


8*127 


13.481 


2*7 


4.6 


2.3 


1*2 


0.6 


0.3 


0.3 



t Samples are exponentially distributed. 
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SCIENTIFIC APPLICATIONS SUBPROGRAMS 



This section presents timings of selected $SCILIB routines and some 
comparisions between $SCILIB routines and FORTRAN DO-loops performing the 
same functions. Table B-2 gives timings and statistics for ten popular 
DO-loops and their $SCILIB equivalent subroutines. The FORTRAN DO-loops 
are compiled with CFT version 1,10. The $SCILIB version is 1*11. The 
timings in the tables are generated on a CRAY-1 S Series 16-bank machine. 

The timings for these tables are generated by a routine in SCILBPL called 
TIMINGS. The following job produces timings for various machines with 
the default compiler and $SCILIB. 

J0B,JN=TIMINGS. 

ACCOUNT, hC=myoun. 

CFT. 

LDR. 

/EOF 

CALL TIMINGS 

STOP 

END 

The output appears in $OUT. 

The following job produces timings for various versions of CFT or $SCILIB. 
JOB,JN=TIMINGS. 

account , hC=myown . 

ACCESS, DN=$SCILIB, IV^myoDn. 

ACCESS , DN~CFT , Tb**mycwn . 

ACCESS , DN=SC ILBPL , ID=myotfn. 

UPDATE, P«SCILIBPL, I*0,Q=TIMINGS . 

CFT,I=$CPL. 

CFT. 

LDR. 

/EOF 

CALL TIMINGS 

STOP 

END 

Subroutine name - name of the $SCILIB routine and a brief description 
of its function 

Loop length - the number of passes through the FORTRAN DO- loop 

CFT time - seconds used computing the results with CFT version 1.10 

$SCILIB time - seconds used computing the same result with a call to a 
$SCILIB subroutine 

$SCILIB/CFT - the ration of $SCILIB time to CFT time 
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Cloaks per operation - number of 12.5 nanosecond clocks per 
floating-point operation or per loop length if no floating-point 
operations are done 

Two points are evident from the column of ratios between CFT DO-loop and 
$SCILIB subroutines. 

1. The overhead of a subroutine call dominates the execution time 
for short loop lengths. 

2. For long loop lengths , $SCILIB versions can be faster than CFT 
versions by a factor of 2 or 3. 

Table B-3 presents timings and MFLOP rates for $SCILIB versions of SGEFA 
and SGESL of LINPACK and ELMHES and HQR of EISPACK. 

Subroutine name and function - name of $SCILIB routine and a brief 
description 

Dimension of matrix - the size of the matrix problem 

Execution time - second used to compute the result 

MFLOP rate - the approximate number of millions of floating-point 
operations per second 
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Table B-2. $SCILIB timings and comparisons 



Subroutine Name 


Loop 


CFT Time 


SSCILIB 


4SCILIB/ 


Clocks Per 


(Function) 


Length 


(xl0*~6 sec) 


Time 


CFT 


Operation 








<xl0~ 6 sec) 


(Ratio) 




FOLR 


1 


2.5 


3.9 


1.58 


315. 


(first order 


2 


3.1 


4.1 


1.32 


165. 


linear recurrence) 


3 


3.7 


4.3 


1.18 


87. 




4 


4.3 


4.6 


1.08 


61.33 




5 


4.8 


4.8 


1.00 


48.00 




10 


7.6 


5.9 


.78 


26.33 




25 


16. 


9.3 


.58 


15.50 




50 


30. 


15. 


. 50 


12.18 




100 


58. 


26. 


.45 


10.59 




250 


140. 


60. 


.42 


9.63 


GATHER 


1 


3.0 


4.6 


1.57 


371. 


A (I) »B (INDEX (I) ) 


2 


3.4 


4.8 


1.43 


193. 




3 


3.8 


5.0 


1.32 


133.67 




4 


4.2 


5.1 


1.22 


102.75 




5 


4.6 


4.9 


1.07 


79.2 




10 


6.7 


5.6 


.84 


44.7 




25 


13. 


7.5 


.58 


24. 




50 


23. 


11. 


.46 


17.10 




100 


44. 


17. 


.39 


13.65 




250 


110. 


36. 


.34 


11.58 


ISAMIN 


1 


2.5 


6.2 


2.48 


493. 


(finds the 


2 


3.4 


6.2 


1.83 


494. 


first position 


3 


4.2 


6.2 


1.46 


247.50 


of the minimum 


4 


5.1 


6.2 


1.22 


165.33 


absolute value 


5 


6.0 


6.2 


1.04 


124.25 


of a vector) 


10 


10. 


7.1 


.69 


63.11 




25 


23. 


9.0 


.39 


30.08 




50 


45. 


11.0 


.25 


18.04 




100 


88. 


51. 


.58 


41.55 




250 


220. 


70. 


.32 


22.33 
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Table B-2. $SCILIB timings and comparisons (continued) 



Subroutine Name 


Loop 


CFT Time 


$SCILXB 


$SCILIB/ 


Clocks Per 


(Function) 


Length 


(xl0~ 6 sec) 


Time 


CFT 


Operation 








(xl0~ 6 sec) 


(Ratio) 




ISRCHEQ 


1 


4.3 


5.5 


1.27 


438.00 


(searches a 


2 


4.7 


5.5 


1.55 


219.49 


vector for 


3 


5.2 


5.5 


1.06 


146.67 


a word 


4 


5.6 


5.5 


0.97 


110.25 


match) 


5 


6.1 


5.5 


0.90 


88.40 




10 


8.3 


5.6 


.67 


44.70 




25 


15. 


5.8 


.38 


18.48 




50 


28. 


6.1 


.21 


9.74 




100 


50. 


7.0 


.14 


5.59 




250 


110. 


9.1 


.07 


2.90 


MXM M 


1 


6.6 


5.5 


.64 


443. 


(full matrix 


2 


24. 


6.5 


.46 


57.44 


multiply) 


3 


25. 


8.0 


.32 


18.37 




4 


40. 


9.2 


.23 


8.07 




5 


59. 


12. 


.20 


5.04 




10 


220. 


30. 


.13 


1.38 




25 


1700. 


260. 


.16 


.71 




50 


8900. 


1800. 


.20 


.59 




100 


59000. 


14000. 


.24 


.57 




250 


770000. 


210000. 


.27 


.54 


MXM V 


1 


5.8 


5.6 


.97 


447. 


(matrix 


2 


7.6 


6.4 


.85 


102.2 


times a vex tor) 


3 


9.3 


6.5 


.70 


40. 




4 


11.0 


7.0 


.63 


22.44 




5 


13.0 


7.3 


.56 


12.4 




10 


23.0 


9.8 


.42 


4.35 




25 


66. 


24. 


.37 


1.62 




50 


180. 


76. 


.43 


1.24 




100 


580. 


280. 


.49 


1.14 




250 


3100. 


1700. 


.55 


1.09 


SAXPY 


1 


3.3 


5.3 


1.60 


212.5 


(add a scalar 


2 


3.3 


5.3 


1.60 


106.5 


multiple of 


3 


3.3 


5.3 


1.59 


71.17 


one vector 


4 


3.4 


5.3 


1.59 


53.50 


to another) 


5 


3.4 


5.4 


1.59 


42.90 
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Table B-2. $SCILIB timings and comparisons (continued) 



oujjrouxxne Maine 


XiOOp 

T.pnctf h 


PPm rp 4 triA 
t-J: X X lIRc 

/y 1 A ""6 car \ 


■POV^XXjXJD 

(xlO" 6 sec) 


•CpTT TD / 
ipdl^XXiXD/ 

CFT 

(Ratio) 


LiUCKS ret 

Ooeration 

>^ Wr JU U w J. 1 A 


SAXPY (continued) 


10 


3.5 


5.5 


1.58 


21.95 




25 


4.0 


6.0 


1.50 


9.66 




50 


5.0 


7.0 


1.41 


5.58 




100 


7.3 


9.3 


1.28 


3.72 




250 


14.0 


16. 


1.15 


2.52 


SCATTER 


1 


2. 7 


6- 0 


2.24 


482. 00 


A I X JXIXD A \ ± J J —15 \ X ^ 




^ n 






241.5 




3 


3.0 


6.1 


1.81 


161.33 










1- 66 


121. 25 




5 


4.0 


6.1 


1.52 


97.20 




10 


5.6 


6.9 


1.23 


55.20 




25 


10. 


8.8 


.83 


28.00 




50 


19. 


12. 


.63 


18.66 




100 


35. 


19. 


.53 


14.90 




250 


84. 


39. 


.46 


12.42 


SDOT 


1 


2.9 


5.5 


1.89 


439. 




2 


7.1 


5. 5 


. 77 


146.33 


dot product of 


3 


7.1 


5.5 


.77 


87.80 




4 


7.2 


5.5 


.77 


62.71 




5 


7.2 


5.5 


.76 


48.78 




10 


7.3 


5.6 


.76 


23.63 




25 


8.2 


6.0 


.73 


9. 78 




50 


9.8 


6.6 


.68 


5.34 




100 


13. 


7.8 


.59 


3.15 




250 


23. 


12. 


.51 


1.93 


SSUM 


1 


2.6 


3.9 


1.52 


314. 


( sums the 


2 


6.6 


4.1 


.62 


326. 


elements of 


3 


6.6 


4.2 


.64 


169. 


a real vector) 


4 


6.6 


4.4 


.66 


116. 




5 


6.6 


4.5 


.68 


90.5 




10 


6.8 


4.8 


.71 


42.89 




25 


7.2 


5.0 


.69 


16.71 




50 


8.2 


5.3 


.65 


8.69 




100 


10. 


7.0 


.67 


5.66 




250 


17. 


9.1 


.55 


2.92 
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Table B-3. $SCILIB timings and MFLOP rates 



Subroutine Name 


Dimension of 


Execution 


MFLOP rate 


\£ Lull*, t XUII / 




f into ( cop^n^cl 




ELMHES 


5 


.000057 


3.63 


(Keauctiion or 


i n 
1U 


. UUUZO 


6. 32 


run matrix 


25 


Anon 
• 0020 


13*30 


to upper 


50 


• 010 


20.23 


nessenDerg rormj 


1UU 


• Uo4 


25* 83 




o^n 


Q "5 

tOJ 


Ji» 42 


HQR 


5 


.00053 


2,25 


(Keaucuion rorm 


10 


n n o o 
• 0022 


4.70 


u^^/c^i. ijcoociiuci y 




01 1 


XX • 41 








01 

/l * UD 






1 P 
• lo 






0R0 


1 A 

Mm t 


AO AO 
• OZ 


SGEFA 


5 


.000062 


1.35 


(L— U decomposition) 


10 


•00019 


3.48 




25 


• 0011 


9 .62 




50 


• 0048 


17.41 




100 


• 026 


25.51 




250 


.30 


35.00 


SGESL 


5 


.000049 


1.73 


(Backward and 


10 


.000056 


3.59 


forward solving) 


25 


.00015 


8.58 




50 


.00033 


15.01 




100 


.0089 


22.01 




250 


.039 


32.58 
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SORT ENTRY POINTS 



C 



SORT consists of library subroutines accessed through FORTRAN calls. The 
user-callable entry points are as follows: 

SAMSORT 

SAMFILE 

SAMKEY 

SAMGO 

SAMEQU 

SAMOPT 

SAMSEQ 

SAMSIZE 

SAMTUNE 

Following are the entry points within the CRI sort package. The code is 
proprietary and must not be used for any purpose other than as part of 
the CRI sort package* 

Module PSRV8I0 entry points Module IOXOXOI entry points 



V8PUT 


P87DNT 


V8GET 


P87DOD 


V8WAIT 


P87CLS 


V8POS 


P87DLT 


V8CL0SE 


P87WDC 


V80PEN 


P87RDC 


V8STATS 


P87LBN 


V8LNTHDS 


P870PN 




P87WAIT 




P87SNSE 



For more details, see the SORT Reference Manual, CRI publication SR-0074. 
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Abort current job step, 8-2 
Abort with traceback, 2-4 
ABORT, 2-4, 7-36 
ABS, 2-4 , 3-29 
Absolute program, 2-48 
Absolute value 

minimum, 4-26 

sum, 4-3# 4-5 
ACCESS, 2-4, 6-2 
ACOS, 2-4, 3-8, A-l 
ACPTBAD, 2-4, 5-76 
ACQUIRE, 2-5, 6-3 
ACTTABIiE , 2-5, 7-70 
Addition, double-precision, 2-2 2 
ADDLFT, 2-6, 6-5 
ADJUST, 2-5, 6-2 
ADW, 7-16 
AIMAG , 2-5, 3-2 9 
AINT, 2-5, 3-29 
ALF, 6-5 
Algorithms, A-l 
ALLOC, 2-37, 7-26 
Allocate routines, 7-25 
ALOG, 2-49, 3-5, A-2 
ALOG10, 2-49, 3-5 
AMOD, 2-6, 3-29 
AMU, 2-6, 7-19 
AND, 2-6, 3-13 
ANINT, 2-6, 3-29 
APBN, 2-60, 5-53 
APUTWA, 5-105 

Arccosine, 2-4, 3-8, A-l, A-9 
Arcsine, 2-7, 3-8, A-10 
Arctangent 

double-precision, 2-18, A-10 

double-precision 2 -argument, 2-19 

two-argument, A-3, 2-8 

one-argument,, 2-7, 3-8, 3-9, A-2 
ARERP, 2-6, 7-60 
ARGPLIMQ, 2-33, 2-7, 7-3 
Argument 

as substring, 2-12 

length, 2-12 

first word address, 2^48 
Argument values, 2-7 
Arithmetic routines 

double-precision, 3-17 

triple-precision, 3-18 

triple-precision, 3-19 

triple-precision, 3-20 



Array 

bounds checking, 2-48, 7-12 
complex, 2-8, 2-7 0, 2-71, 2-8 0, 2-81 
copy, 4-3 

Euclidean norm of, 4-3 

indexed, 4-64 

interchange, 4-22 

largest absolute value in, 2-4 5 

maximum of, 2-46 

minimum of, 2-46 

ordered, 2-71 

real, 2-8, 2-70, 2-BO, 2-81 
scale, 4-4 
scaling, 2-70 

search for target, 2-71, 4-71 

swap, 4-22 

swap two, 4-4 

task control, 2-8 6 

true values in, 2-42 

with integer target, 4-60, 4-65 

with real target, 4-59, 4-65 

with true relational value to 
target, 2-92 

zero values in, 4-5 8 
ASCDC, 2-7, 5-33 
ASCII conversion, 3-2 5, 3-2 6 
ASIN, 2-7, 3-8 
ASPOS, 2-74, 5-46 
ASSIGN, 2-7, 6-3 
ASYNCHMS/ASYNCDR, 5-9 6 
A TAN, 2-7, 3-8, A-2 
AT AW 2 , 2-8, 3-8, A-3 
ATS, 2-8, 7-15 



B20CT, 2-30, 7-10 
BACK, 2-8 

BACKFILE, 2-8, 5-52 
Backspace 

record, 2-8 

file, 2-8 
BACKSPACE, 5-51 
Bad data, 2-4, 5-75 

Basic Linear Algebra Subprograms (BLAS) 

description, 4-1 

list, 4-3 
Bibliography, A-2 0 
BICONV, 2-9, 7-68 
BICONZ, 2-9, 7-68 

Bidirectional memory transfer, 2-12 and 

2-13, 2-72, 73, 7-40 
Binary image, 2-48 
Bit setting, 2-42 
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Bits 

move, 2-53 

tally number set, 2-61 

parity of number set, 2-61 

number set to 1, 3-14 
BKSP, 2-8, 5-50 
BKSFF, 2-8, 5-52 

BLAS, see Basic Linear Algebra Subprograms 

Boolean arithmetic routines, 3-13, 14 

Breakpoint checking (Pascal) , 2-96 

BTD, 2-9, 3-26 

BTDL, 2-9, 3-26 

BTDR, 2-9, 3-26 

BTO, 2-9, 3-26 

BTOL, 2-10, 3-26 

BTOR, 2-10, 3-26 

Bucket sort, 4-75 

BUFFER I/O, 2-47, 2-87 

Buffer management 

input, 5-16 

output, 5-17 
Buffered output, 2-91 
Byte and bit manipulation, 7-63 
Byte storage, 2-61 
Bytes 

fetches, 2-41 

compares, 2-47 

move, 2-80 



CABS , 2-10, 3-30, A-3 

CAL I/O interface, 5-75 

Call-by-value routine (Pascal) , 2-96 

Calling routine (Pascal) , 2-96 

Calling task, 2-20 

CAXPY, 2-8, 4-3, 4-7 

CBIO, 5-7 5 

CC120I, 5-19 

CC120O, 5-20 

CCF, 2-11, 3-25 

CCHRO, 5-20 

CCI, 2-11, 3-24 

CCOPY, 2-14, 4-3, 4-8, 2-10 

CCOS, 3-9, A-4 

CCS, 2-17, 7-46 

CCT, 2-11, 3-24 

CD120I, 5-19 

CD120O, 5-20 

CDCI, 2-11, 5-18 

CDCO, 2-11, 5-18 

CDOTC, 4-4 , 4-9 

CDOTC, CDOTU, 2-21 

CDOTU, 4-10, 4-4 

Ceiling of rational number, 2-41 

CEXP, 2-31, 3-6, A-4 

CEXPR, 2-11, 7-54 

CF60I, 5-19 

CF60O, 5-20 

CFFT2, 2-31, 4-51 

CFT call type, 2-3 

CFT in-line functions, 3-13 

CFT linkage macros, 1-2 

CFT linkage methods, 1-2 

Change length and move routines, 7-29 



CHAR, 3-30 
Character address 

increment, 5-7 8 
Character functions 

called from CAL, 3-2 3 

called from FORTRAN, 3-22 
Character routines, 5-77 
Character string 

searches for occurence of, 2-32 
CHCONV, 2-12 
CHCONV, 7-67 
CHECKMS/CHECKDR , 5-9 7 
CI60I, 5-19 
CI60O, 5-20 
Circular shift, 3-14 
CL60I, 5-19 
CL60O, 5-20 
CLEARBT, 2-12, 7-41 
CLEARBTS, 2-13, 7-42 
CLEARFI, 2-13, 7-39 
CLEARFIS, 2-13, 7-40 
CLMOVE, 2-37, 7-29 
CLOCK, 2-13, 7-42 
CLOG, 2-49, 3-5, A-4 
CLOSE, 2-13, 5-34, 6-8 
CLOSEWA, 5-110 
CLOSMS, 2-53 

CLOSMS/CLOSDR, 5-91, 5-92 

CMACH, 2-77, 4-30 

CMPLX, 2-14, 3-30 

Common block TM, 7-14 

Common logarithm, 3-5 

Common mathematical subprograms, 2-97 

Compare 

ASCII, 3-22 and 3-23 
Compares 

for greater than, 2-11 

for less than, 2-12 

for less than or equal to, 2-12 

for nonequality, 2-12 
COMPL, 2-14, 3-13 
Complex 

absolute value, A-3, 3-30 

conjugate, 3-30 

cosine, A-4, 3-9 

exponential, A-4 

exponentiation, 3-6 

imaginary portion of, 3-2 9 

logarithm, A-4 

real portion of, 3-34, 4-7 

sine, 3-9, A-7 

square root, 3-7, A- 8 

vector, 4-6, 4-8 
Complex absolute value, 2-10 
Complex array 

copies , 2-14 
Complex conjugate, 2-14 
Complex cosine, 2-10 
Complex logarithm, 3-5 
Complex number 

imaginary part, 2-5 

real part of, 2-6 5 
Complex sine, 2-17 
Compute absolute value, 2-4 
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Conca tena t ion 

initialize for store, 3-24 
CONJG, 2-14, 3-30 
Contangent, d,p., A-ll 
Control information tables , 7-12 
Control statement 

cracks, 2-17 
Control statement processing, 7-46 
Conventions in manual, 1-3 
Conversion 

ASCII, 3-2 6 

character to integer, 3-32 
Cray/other vendors, 5-20 
integer to character, 3-30 
return conditions, 5-81 
Convert 

ASCII/display code, 5-33 

ASCII/EBCDIC, 5-27 

ASCII to EBCDIC, 2-88 2-24 

ASCII to integer, 7-67 

between timestamps and date and 

time, 2-8 4, 7-44 
binary to decimal, 3-26 
binary to octal/ 3-2 6 
CDC to Cray, 2-32, 2-44 
Cray/CDC integer, 5-32 
Cray /CDC single-precision, 5-33 
CDC/Cray integer, 5-31 
CDC/Cray single-precision, 5-31 
Cray/IBM integer, 5-26 
Cray /IBM logical, 5-28 
Cray/IBM single precision, 5-24 
Cray integer/IBM decimal, 5-28 
Cray single-precision to IBM 

double-precision, 2-88, 5-25 
Cray to CDC, 2-3 2, 2-44 
date and time to times tamp, 2-84 
decimal to binary, 3-26 
display code/ASCII, 5-32 
display code to ASCII character, 2-24 
EBCDIC/ASCII, 5-22 

from date and time to timestamp, 7-44 
from real-time clock value to 

timestamp, 7-45 
from timestamp to real-time clock 

value, 7-45 
IBM/Cray integer, 5-21 
IBM/Cray logical, 5-23 
IBM integer to Cray integer, 2-88 
IBM packed decimal integer, 5-23 
integer to ASCII, 7-68 
integer to binary, 2-24 
integer to IBM packed decimal, 2-88 
integer to real, 2-33, 3-32 
nearest integer to double-precision, 

3-32 

numeric input, 2-56 

numeric output, 2-5 7 

octal to binary, 2-59, 3-26 

real to double-precision, 2-19, 3-3 0 

real-time to corresponding timestamp 

value, 2-84 
timestamp to corresponding real-time 

clock value, 2-84 



Convert (continued) 

trailing blanks to nulls, 7-8 5 
trailing nulls to blanks, 7-85 
two reals to a complex, 3-30 
Converts 

ASCII character to display code 

character, 2-7 
ASCII to integer, 2-12 
binary to decimal, 2-9 
binary to octal, 2-9 
binary to octal, 2-10 
Cray integer to IBM integer, 2-89 
Cray logical to IBM logical, 2-89 
Cray single-precision to IBM 

single-precision, 2-90 
EBCDIC to ASCII , 2-87 
IBM logical to Cray logical, 2-89 
IBM packed decimal field to 

integer , 2-89 
IBM single-precision to Cray 

single-precision, 2-89 
integer to ASCII, 2-9 
IBM/Cray single-precision, 5-20 
IBM/Cray single-precision, 5-21 

Copy 

vector, 4-8 
COP YD, 5-39 
COPYF, 2-15, 5-37 
COPYR, 2-15, 5-35 
COPYU, 2-15, 5-39 
COS, 2-15, 3-9, A-5 
COSH, 2-15, 3-11, A-5 
Cosine 

double-precision, 2-19 

d.p, hyperbolic, A-ll 
Cosine and sine, 3-10 
Cosine, 2-15, 2-16, 3-9, A-5 
Cosine, complex, A-4 
Cosine, d.p*, A-ll 
COSS, 2-16, 3-10, A-5 
COSSK, 2-16, 3-11 
COT, 2-16, 3-10, A-7 
Cotangent, 2-16, 3-10, A-7 
CRACK, 2-16, 7-52 
CRAY channel 

program on an IOS, 2-23 
Cray machine constants, 4-29 
CRAYDUMP, 2-26, 7-8 
CRFFT2, 2-31, 4-53 
CROT, 2-67, 4-28 
CROTG, 2-67, 4-28 
CS, 2-17, 7-46 
CSCAL, 2-70, 4-22, 4-4 
CSIN, 2-17, 3-9, A-7 
CSQRT, 2-78, 3-7, A-8 
CSSCAL, 2-70, 4-22, 4-4 
CSUM, 2-80, 4-27 
CSWAP, 2-81, 4-23, 4-4 
CTOC, 2-17, 3-15, A-8 
CTOI, 2-17, 3-15, A-9 
CTOR, 2-18, 3-15, A-9 
Current date, 2-19, 8-10, 8-14, 8-4 
Current time, 8-23 
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DABS, 2-18, 3-30 
DACOS, A- 9 
DACOX, 3-8 
DAS IN , 3-8, A-10 
DASS, 2-22, 3-17 
DASV, 2-2 2 , 3-17 
Data copies, 2-15 

Data format management input, 5-18 
Data management format output, 5-19 
DATAN, 2-18, 2-19, 3-9, A-10 
DATAN2, 3-9 
Data set 

accessed, 6-6 

assigns characteristics to, 2-7 
asynchronously positions , 2-60 
attributes, 6-3 
buffers, 2-90 
bypass records in, 2-76 
bypass files in, 2-76 
characteristics, 2-53 
change records of, 2-53 
CLOSE, 5-34 

close, 2-13, 5-110, 6-3, 6-8 

closing, 5-92 

Connect, 2-58 

control use of, 2-60 

copies, 2-14 

copying, 5-35 

copy, 5-39 

current size, 6-7 

definitions table, 6-9 

direct to specified queue, 2-21 

edition number, 2-55 

foreign, 2-69, 2-94 

front-end resident, 2-5 

interactive, 8-12 

load absolute program from, 7-78 

local to job, 2-41 

mass storage, 5-42, 5-46, 5-48 

OPEN, 5-34 

open, 2-58, 2-90, 2-7, 2-96, 6-3, 

6-7, 8-11 
open local, 5-84 
permanent, 2-82, 6-2 
places into input queue, 2-80 
position, 2-61, 5-53 
positioning, 2-69, 2-74, 2-76, 

5-42, 5-47 
query interactive, 2-96 
random access, 2-9 0, 5-89, 5-9 0, 

5-91, 5-103 
random, unblocked, 6-7, 2-63, 6-8 
read, 2-69 
release, 2-65 

rewind, 2-96, 5-52, 8-10, 2-66 
saved, 6-2 
search, 6-4 
size, 2-57 
skip, 5-40, 5-41 
staging, 6-2 
status, 2-43, 5-35 
synchronize, 5-55 
synchronously positions, 2-60 
tape, 2-81, 5-4 4, 5-45, 5-47 



Dataset (continued) 

terminates connection of, 2-13 

termination, 5-55 

unblocked, 2-76, 7-6 

word-addressable, 5-109 and 5-110 

write, 2-94 
Dataset Catalog 

removes saved dataset from, 2-20 
Dataset catalog, 6-2 
Dataset control, 5-34 
Dataset management, 6-1 
Dataset Parameter Table (DSP) 

search, 6-4 

search for address, 6-6 
Dataset parameter tables 

search, 2-71 
Dataset position, 2-3 6 
Datasets 

system, 2-71 

FORTRAN access, 2-71 

word-addressable, 5-111 
Date (Pascal) 

obtain, 2-96 
Date and time, 7-42 
DATE, 2-19, 7-42 
DAVS, 2-22, 3-17 
DAW, 2-22, 3-17 
DBLE, 2-19, 3-30 
DCOS, 2-19, 3-9, A-ll 
DCOSH, 3-11, A-ll 
DCOT, 3-10, A-ll 
DDIM, 2-20, 3-30 
DDSS, 2-22, 3-17 
DDSV, 2-22, 3-17 
DDVS, 3-17 
DDW, 2-22, 3-17 
DEADBOG, 2-81, 7-7 
DEALLC, 2-37, 7-27 
Deallocate routines, 7-26 
Debug aid, 7-1 
Decode 

formatted, 5-3, 5-7, 5-14 
Decoding routines, 2-20 
Definition and control, 6-3 
DELETE, 2-20, 6-2 
DELTSK, 2-20, 9-13 
DEV, 2-20 

DEXP, 2-31, 3-6, A-ll 
DFA, 2-20, 5-7 
DFF, 2-20, 5-14 
DFI, 5-3 
DFV, 5-7 
Difference 

positive integer, 2-41 
DIM, 2-20, 3-31 
DINT, 2-21, 3-31 
Display code conversion, 2-2 4 
DISPOSE, 2-21, 6-3 
Divide, 8-5 
Division 

compute remainder, 2-6 

double-precision, 2-22 

integer, 2-96 

64-bit, 2-52 

64-four-bit integer, 3-21 
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Division remainder , 2-21 
DLOG, 2-50, 3-5, A-12 
DLOGl 0 f 3-5 

DMOD, 2-21 , 2-51, A-13 
DMSS r 2-22, 3-17 
DMSV, 2-23, 3-17 
DMW, 2-23, 3-17 
DNINT, 2-21 r 3-31 
Dot produce, 2-21, 2-2 2 
Dot product, 4-4 
Double-pr ec i sion 

absolute value, 2-18, 3-30 

addition, 2-22, 3-17 

arcosine, 3-8, A-9 

arcsine, 3-8, A-10 

arctangent, 2-18, 2-19, 3-9, A-10 

arithmetic routines, 3-17 

common logarithm, 3-5 

conversion, 2-88 

cosine, 2-19, 3-9, A-ll 

cotangent, 3-10, A-ll 

division, 2-22, 3-17 

exponential, 2-31 

exponentiation, 3-6, A-ll, A-14 

hyperbolic cosine, 3-11, A-ll 

hyperbolic sine, 3-11, A-13 

hyperbolic tangent, 3-12, A-14 

logarithm, 2-50 

modulo arithmetic, 2-51, 3-31, A-13 
multiplication, 2-22, 2-23, 3-17 
natural logarithm, 3-5, A-12 
nearest integer to a, 3-3 2 
negative powers of 10, 2-43 
positive powers of 10, 2-44 
positive real difference, 2-20, 3-30 
product, 2-23 

product of two real arguments, 3-31 

raise power, 2-2 5, 2-26 

sine, 2-24, 3-10 

square root, 3-7, A-13 

subtraction, 2-22, 2-23, 3-17 

tangent, 3-10, A-14 

transfer sign, 3-32 

truncate, 2-21, 3-31 
DPROD, 2-23 
DRIVER, 2-230 7-7 0 
DSASC, 2-24, 5-32 
DSIGN, 2-24, 3-32 
DSIN, 2-24, 3-10 
DSINH, 3-11, A-13 
DSNDSP, 2-24, 6-5 
DSP 

set end-of-fiie flag, 2-87 
DSQRT , 2-78, 3-7 
DSSS, 2-22, 3-17 
DSSV, 2-23, 3-17 
DSVS, 2-23, 3-17 
DSW, 2-23, 3-17 
DTAN, 3-10, A-14 
DTANH, 3-12, A-14 
DTB, 2-24, 3-26 
DTOD, 2-25, 3-15, A-14 
DTOI, 2-25, 3-16, A-14 
DTOR, 2-26, 3-16 



DTTS, 2-84, 7-44 

Dump heap control word routines, 7-33 
Dump routines, 7-5 
DUMP, 2-26, 7-6, 8-4 
DUMPJOB, 2-27, 7-6 



ECHO, 2-27, 7-71 
EFA encode 

formatted, 5-11 
EFA, 2-27 
EPF, 2-27, 5-15 
EFI, 2-27, 5-5 
EFV, 2-27, 5-12 
Eigenvalue problem, 4-3 8 
EISPACK routines 

descriptions, 4-3 8 

summary, 4-42 
EISPACK, 2-27 

Encode formatted, 5-5, 5-12, 5-15 
End 

program, 2-96 

end of file check, 2-96 

end of line check, 2-96 
End of file mark, 8-15 
End of file mark, 8-25 
END, 2-27, 7-36 

End-of-file status, Pascal, 8-6 

End-of-line status, Pascal, 8-6 

ENDF1LE, 5-56 

ENDRPV, 2-28, 2-65, 7-36 

Entry type, 2-2 

EOATEST, 2-28, 5-58 

EOD, 2-91 

EODW, 2-28, 5-5 6 

EOF, 2-29, 2-91, 5-58 

EOFR, 2-28, 5-56 

EOFW, 2-28 

EOR, 2-91 

EQ, 2-12, 3-23 

Equations Weiner-Levinson, 2-32 

EQV, 2-29, 3-13 

E RECALL , 7-72 

ERREXIT, 2-29, 7-3 6 

Error processing, 2-6 

Error processing routines, 7-60 

Error recovery, 5-75 

Errors 

I/O, 2-44 

NAMELIST, 2-4 4 

processes $FTLIB, 2-33 

process $ SCI LIB , 2-70 

process $UTLIB, 2-90 

processes 3SYSLIB, 2-76 
Euclidean norm, 2-71, 2-77, 4-10, 4-3 
EVASGN, 2-29, 9-9 
EVCLEAR, 2-29, 9-10 
Event processing, 2-29, 2-3 0 
Event routines, 9-9 
EVPOST, 2-29, 9-9 
EVREL, 2-30, 9-10 
EVTEST, 2-30, 9-10 
EVWAIT, 2-30, 9-9 
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Exchange package 

printout, 7-11 

write to output dataset, 7-9 
Exchange Package processing, 2-30, 7-8 
Exit program, 2-96 
EXIT, 2-30, 7-36 
EXP, 2-31, 3-6, A-14 
Explicit data conversion, 5-20 
Exponential 

complex, 2-31, A-4 

double-precision, 2-31 
Exponential routines, 3-6 
Exponentiation, A-14, A-15, A-17, A-18 
Exponentiation, complex, A-8, A-9 
Exponentiation, d.p. , A-ll 



Past Fourier Transform, 2-31, 4-50 

FDBKSP, 2-69, 5-51 

FDGPOS, 2-69, 2-69, 5-44 

FDSPOS, 2-69, 5-48 

FDWEOF, 2-94 

FETCH, 2-31, 6-3 

FFS, 5-78 

File 

backspace, 5-52 
reset, 2-97, 8-19 
rewrite, 2-97 

rewrite without rewind, 2-9 6 
File name set, 2-96 
Files 

copies, 2-15 

copy, 5-37 

skip, 5-40 
Filter analysis and design, 4-53 
Filter coefficients, 2-3 2 
FILTERG, 2-32, 4-54 
FILTERS, 2-3 2, 4-54 
Finalization 

input, 5-14 

output, 5-14 
FINDCH, 2-32, 7-66 
FINDMS, 2-53, 5-94 
FLOAT, 2-33, 3-32 
Floating-point interrupt 

permanent, 7-39 
Floating-point interrupt 

temporary, 7-39 
Floating-point interrupt 

test routine, 7-39 
Floating-point interrupts, 2-72, 2-73 
Floating-point seconds, 2-85 
Flow trace, 7-2 
FLOWENTR, 2-33, 7-2 
FLQWEXIT, 2-33, 7-2 
FLOWLIM, 2-33, 7-4 
FLOWSTOP, 2-33, 7-2 
Flowtrace processing, 2-33, 2-7 3 
FOLR, 2-34, 4-30 
FOLR2, 2-34, 4-32 
FOLR2P, 2-34, 4-32 
FOLRN, 2-34, 4-3 3 
FOLRP, 2*34, 4-31 
Format search, 5-78 



Formatted output, 2-91 

FORTRAN I/O 

description, 5-1 
f inalization , 5-14 
initialization, 5-3 
summary » 5-2 
transfer, 5-5 
FP6064, 2-32, 5-31 
FP6460, 2-32, 5-33 
FSPOS, 2-7 4, 5-4 7 
FTERP, 2-33, 7-61 
FXP, 2-30, 7-10, 7-9 



GATHER, 3-35, 4-56 
Gauss-Jordan elimination, 4-4 6 
Gauss-Jordan reduction, 2-51 
GE, 2-11, 3-23 
GETB1, 2-35, 7-74 
GETDSP, 2-35 
GETLPP, 2-35, 7-74 
GETNAMEQ, 2-35, 7-2 
GETPARAM, 2-36, 7-49 
GETPOS, 2-36, 2-74, 5-4 5 
GETREGS, 7-3 
GETSDP, 6-6 
GETWA, 2-90, 5-106 

Givens plane rotation, 2-67, 4-11, 4-13, 

4-19, 4-28, 4-4 
GP, 2-36 

GPARAM, 2-36, 7-50 
GPOS, 2-36, 2-74, 5-42 
GT f 2-11, 3-23 
GTDSP, 6-6 
GTPOS, 2-36, 5-44 



Hardware performance monitor, 2-60, 7-82 

HCHECK, 2-37, 7-32 

Heap block length routines, 7-30 

Heap control block, 8-1 

Heap expansion routine, 7-34 

Heap integrity check routines, 7-31 

Heap manager, 7-25 

Heap memory request routine, 7-3 4 

Heap merge routine, 7-35 

Heap processing (Pascal), 2-9 6 

Heap processing, 2-37, 8-8 

Heap shrink routines, 7-31 

Heap statistics routines, 7-32 

H MERGE , 2-37, 7-35 

HPALLOC, 2-37, 7-26 

HPCHECK, 2-37, 7-32 

HPCLMOVE, 2-37, 7-30 

HPDEALLC, 2-37 

HPDUMP, 2-37, 7-33 

HPGROW, 2-37, 7-34 

HPLEN, 2-37, 7-30 

HPMEM, 2-37, 7-3 4 
H PMEWLEN , 2-37, 7-28 
HPSHRINK, 2-37, 7-31 
HP STAT, 2-37, 7-32 

Hyperbolic cosine and sine, 2-16, 3-11 
Hyperbolic cosine, 3-11, A-5 
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Hyperbolic routines, 3-11, 3-12 
Hyperbolic sine, 2-75, 3-11 
Hyperbolic tangent, 2-83, 3-11, A-19 
Hyperbolic tangent, d.p., A-14 



I/O mode, 5-96 
I/O status, 5-57 
I00DEL, 2-38, 7-57 
I00ERR, 2-38, 7-60 
IQOMVC, 2-38, 7-57 
I00MVM, 2-38, 7-57 
I00ORD, 2-39, 7-58 
1 0 OREAD , 2-39, 7-58 
IO0SETUP, 2-39, 7-60 
I00WRITE, 2-40, 7-59 
IABS, 2-40, 3-32 
IBMI, 2-40, 5-18 
IBMO, 2-40, 5-18 
IC64I, 5-19 
ID640, 5-19, 5-20 
ICAMAX, 2-40, 4-3, 4-5 
ICEIL, 2-41, 7-74 
ICHAR, 3-3 2 
ICHRI, 5-19 
ICHRO, 5-19 
IDIM, 2-41, 3-32 
IDNINT, 2-41, 3-33 
IEOF, 2-29, 5-57 
IF32I, 5-19 
IF320, 5-19 
IFDNT, 2-41, 6-6 
I GTBYT , 2-41, 7-74 
IHPLEN, 2-37, 7-31 
I HP STAT, 2-37, 7-33 
II16I, 5-18 
II160, 5-19 
II32I translate 

IBM integer to Cray integer, 5-18 
II320, 5-19 
IILZ, 2-42, 4-58 
UN, 2-42, 2-82, 3-38 
IJCOM, 7-7 5 
IL8I, 5-19 
IL80, 5-19 
ILLZ, 2-42, 4-58 
ILSUM, 2-42, 4-58 
IMX, 2-43, 2-82, 3-38 
INDEX, 2-12, 3-22 
Initialization 

input, 5-3, 5-4 
Inline code, 1-1 
Input 

buffered, 2-62 
Input transfer 

buffered, 5-8 

formatted and unformatted, 5-6 

namelist, 5-8 
Input/output subprograms, 5-1 
INQ, 2-43 

INQUIRE, 2-43, 5-35 
INSASCI, 2-4 3, 7-76 
INT, 2-43, 3-33, 7-15 
INT6064, 2-44, 5-31, 5-32 



Integer absolute value, 2-40, 3-32 
Integer value 

truncate to, 2-43 
Intersegment subroutine calls, 2-7 2 
Intregral value 

truncate to, 2-5 
IOERP, 2-44, 7-61 
IOSTAT, 2-4 4, 5-58 
IPX, 2-44, 2-82, 3-38 
ISAMAX, 2-45, 4-3, 4-4 
ISAMIN, 2-45, 4-26 
I SEARCH, 2-45 
ISIGN, 2-45, 3-33 
ISMAX, 2-46, 4-25 
ISMIN, 2-46, 4-26 
ISRCH routines, summary, 4-5 9 
ISRCHEQ, 2-45, 4-60 
ISRCHFGE , 2-45, 4-63 
ISRCHFGT, 2-45, 4-62 
ISRCHFLE, 2-45, 4-62 
ISRCHFLT, 2-45, 4-61 
ISRCHIGE, 2-46, 4-64 
ISRCHIGT, 2-46, 4-64 
ISRCHILE, 2-46, 4-63 
ISRCHILT, 2-45, 4-63 
ISRCHNE t 2-45, 4-61 
ITOI, 2-46, 3-16, A-15 



JCLPP 

returns lines from, 2-35 
JDATE, 2-19, 7-43 
J NAME, 2-47, 7-78 
Job Accounting Table (JAT) ,2-5 
Job area image, 2-27 

Job control language symbol routines, 7-55 
Job control routine, 7-35 
Job CPU time, 2-96 
Job name, 2-47 
Job step 

abort, 2-2 9 

terminate and advance, 2-27 

terminates, 2-30 
Job step (Pascal) 

abort, 2-9 6 
JSYMGET, 7-56 
JSYMSET, 7-55 
Julian date, 2-19 



Keyword processing, 2-60 
KOMSTR, 2-47, 7-66 



LCI, 5-77 

LDSS, 2-52, 3-21 

LDSV, 2-52, 3-21 

LDW, 2-52, 3-21 

LE, 2-12, 3-23 

Leading zero bits, 3-13 

LEADZ, 2-47, 3-13 

Left shift, 3-14 

LEW, 2-12, 3-22 

LENGTH, 2-47, 5-57 
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LGE, 2-11 # 3-22 

LGO, 2-48 , 7-78 

LGT, 2-11/ 3-22 

Library list, 1-1 

Library residence, 2-3 

Library summary, 2-1 

Linear algebra subprogram, 4-2 3 

Linear algebra subprograms, summary, 4-25 

Linear equations, 2-51 

Linear recurrence, 2-34, 2-77, 2-78, 4-30 

Linkage macros, 1-2 
LINPACK routines 

descriptions, 4-3 8 

summary, 4-39 
LINPACK , 2-47 

List-directed read, 5-4, 5-7, 5-14 
List-directed write, 5-12, 5-13, 5-15, 5-5 
LLE, 2-12, 3-22 
LLT, 2-12, 3-22 
Load 

character item, 5-77 
LOADC , 2-48 
LOADD, 2-48 
LOADF, 7-12 
LOADI, 2-48 
LOADL, 2-48 
LOADR, 2-48 
LOC, 2-48, 7-7 9 
Lock processing, 2-48, 2-49 
Lock routines, 9-7 
LOCKASGN, 2-48, 9-7 
LOCKOFF, 2-49, 9-8 
LOCKON, 2-49, 9-7 
LOCKREL, 2-49, 9-8 
LOCKTEST, 2-49, 9-8 
Logarithm, 2-49, 2-50 
Logarithm, complex, A- 4 
Logarithm, natural, A- 2 
Logarithm natural d.p«, A-12 
Logarithmic routines, 3-5 
LOGECHO, 7-79 

Logical complement, 2-14, 3-13 
Logical difference, 2-95, 3-13, 3-14 
Logical equivalence, 2-29, 3-13 
Logical File Table 

search, 2-77, 6-5 

search for dataset name, 2-2 4 
Logical File Table (LFT) 

adds name to, 2-6, 6-5 

search, 6-4 
Logical product, 2-6, 3-13 
Logical record I/O, 5-63 
Logical sum, 2-58, 3-13 
LT, 2-12, 3-23 



Machine constants, 2-77, 4-29 
MASK, 3-13 

Mass storage dataset, 5-46 

Mass storage dataset position, 5^4 2 

Math tables, 3-38 

Matrix inverse, 4-46 

Matrix multiplication, 4-13 

Matrix multiply, 2-54, 4-46, 4-47 



Matrix primitive, sparse, 4-24 

Maximum absolute value, 4-4 

Maximum absolute value array complex, 2-40 

Maximum absolute value index, 4-3 

Maximum or minimum value, 4-25 

MEM, 2-51, 7-15 

Memory assignment, 2-51 

Memory dump, 2-26 

Memory management, 2-96 

Memory request, 2-51 

MEMORY , 2-51, 7-79 

Message 

in logfile, 2-65 

insert parameters into, 2-43 
Message classes, 2-27 
Minimum absolute value, 4-2 6 
MINV, 2-51, 4-46 

Miscellaneous math routines, 3-29 

through 3-35 
Miscellaneous special purpose routines, 7-70 
MOD, 2-52, 3-3 3, 3-34 
MODIFY, 2-53, 6-2 
MODSS, 2-52 
MODSV, 2-52, 3-34 
Modulo arithmetic 

double-precision, 3-31 

on integer scalar and integer 
vector, 3-34 

on two integer scalars, 3-33, 3-34 

read, 3-29 

64-bit, 2-52, 3-33, 3-34 
Modulo arithmetic double-precision, A-13 
Modulus, 8-5 
Modulus integer, 2-9 6 
MODVS, 2-52, 3-34 
MODVV, 2-52, 3-34 
MOVBIT, 2-53, 7-63 
Move characters, 2-53 
MOVE, 2-11 
MSC, 2-53, 7-17 
MSCO, 7-17 
MTTS, 2-84, 7-4 5 
Multitasking, 2-86, 9-1 
Multipass sort, 4-7 6 
Multiplication double -precision, 2-23 
MVC, 2-53, 7-64 
MVE, 2-54, 7-20 
MXM, 2-54, 4-46 
MXMA, 2-54, 4-47 
MXV, 2-54 , 4-47 
MXVA, 2-54, 4-49 



NACSED, 2-5 5, 7-81 
Namelist 

auxiliary, 5-59 

input transfer , 5-8 

output transfer routines, 5-13 
NAMELIST I/O errors, 7-61 
NAMELIST processing, 2-55 
Natural logarithm, 3-5, A- 2 
NE, 2-12, 3-23 

Nearest integer, 2-21, 2-57, 3-31, 3-34 
NEQV, 3-13 
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NEWLEN, 2-37 , 7-28 
NICONV, 2-56 , 5-79 
NICV, 2-56, 5-79, 5-82 
NINT, 2-57, 3-34 
NLERP, 2-44, 7-61 
NOCONV, 2-57, 5-8 0, 5-81 
NOCV, 2-57, 5-80, 5-82 
NORERUN , 2-57, 7-3 7 
NUMBLKS, 2-57, 6-7 
Numeric conversion, 5-7 8 



Online translation, v 
OPEN, 2-58, 5-34, 6-7 
OPENMS, 2-53 
OPENMS/OPENDR, 5-8 4 
OPENWA, 5-109 
OPFILT, 2-3 2, 4-5 5 
OPTION, 7-82 
OR, 2-58, 3-13 
ORDERS 

description, 4-73 

examples, 4-7 7 

method, 4-75 

sort times , 4-76 
OS dependency, 2-3 
OSRCHF, 2-71, 4-72 
OSKCHI, 2-71, 4-71 
OTB, 2-59, 3-26 
Output transfer 

buffered, 5-13 

formatted and unformatted, 5-11 
namelist, 5-13 
OVERLAY, 2-59, 7-82 



P$$$HPAD, 2-9 6, 8-1 
P$ ABORT, 2-96, 8-2 
P3 BREAK , 8-2 
P$CALLR, 2-96, 8-2 
P$CBV, 2-96, 8-3 
P$CONNEC, 2-96, 8-3 
PSDATE , 2-96, 8-4 
P$DBP, 2-96, 8-4 
P3DEBUG, 2-97, 8-4 
PfcDISP, 2-96, 8-4 
P$DIVMOD, 2-96, 8-5 
P$ENDP, 2-96, 8-5 
P$EOF, 2-96, 8-6 
P$EOLN, 2-96, 8-6 
PJ$GET, 2-96, 8-6 
P SHALT, 2-96, 8-7 
P3JTIME, 2-96, 8-7 
PSLOGMSG, 2-96, 8-8 
PSLSTREW, 2-96, 8-8 
PfcMEMRY, 2-96, 8-8 
P$MOD, 2-96, 8-9 
P$NEW, 2-96, 8-9 
P30SDBS, 2-96, 8-10 
PSOSDDT, 2-96, 8-10 
P$OSDEP, 2-96, 8-11 
P$OSDJT, 2-96, 8-11 
PSOSDLM, 2-96, 8-11 
P$0SDPR, 2-96, 8-12 



P$OSDQI, 2-96, 8-12 
P$OSDRC, 2-96, 8-12 
P30SDRP, 2-96, 8-13 
P$OSDRW, 2-96, 8-13 
P30SDTM, 2-96, B-14 
PfcOSDWC, 2-96, 8-14 
P$OSDWF, 2-96, 8-15 
P$OSDWR, 2-96, 8-15 
P$OSDXP, 2-96, 8-16 
P$PAGE, 2-97, 8-16 
P$PUT, 2-97, 8-17 
P$RB, 2-97, 8-17 
P$RCH, 2-97, 8-17 
P$READ, 2-97, 8-18 
PSREADLN, 2-97, 8-18 
PfcREPRV, 2-97, 8-19 
P$ RESET, 2-97, 8-19 
P$REWRIT, 2-97, 8-19 
P3RF, 2-97, 8-20 
P$RI, 2-97, 8-20 
P3ROUND, 2-97, 8-21 
P$RSTR, 2-97, 8-21 
P$RTIME, 2-97, 8-21 
PSRTMSG, 2-97, 8-22 
P$RUNT1M, 2-97, 8-22 
P$S FRAME, 2-97, 8-23 
P$TIME, 2-97, 8-23 
P$ TIMER, 2-97, 8-23 
PSTRACE, 2-97, 8-23 
P$TRUNC, 2-97, 8-24 
P$WB, 2-97, 8-24 
P$WCH, 2-97, 8-24 
P3WBOF, 2-97, 8-25 
P$WI, 2-97, 8-25 
p$WO, 2-97, 8-25 
P$WR, 2-97 
PSWRFIX, 8-26 
P$WRFLT, 8-26 
P 3 WRITE , 2-97, 8-2 6 
P$WRITLN, 2-97, 8-27 
PSWSTR, 2-97, 8-27 
P32, 2-59, 5-30 
P6460, 2-59, 5-2 9 
Pack 

3 2-bit words, 2-59, 5-30 

60-bit words, 2-59, 5-29 

words into packed list, 2-59 
PACK, 2-59, 7-68 
PAD, 2-11 

Page start new, 2-97 
Page-eject, 8-16 
PAL, 2-36 

Pascal subprogram summary, 2-96 

Pascal, 8-1 

PAUSE, 2-59, 7-38 

PBN , 2-60, 5-53 

PDD, 2-82, 6-9 

PDUMP, 2-26, 7-6 

PERF, 2-60, 7-82 

Performance counter group descriptions, 7-86 
Performance monitor , 2-60 
Performance statistics, B-l 
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Permanent dataset 

access, 2-4, 2-5 

acquire front-end resident, 2-5 

expand contract, 2-5 
PERMIT, 2-60, 6-2 

Plane rotation, Givens, 2-67, 4-11, 4-13, 

4-19, 4-28, 4-4 
Pocket sort, 4-75 
POPCMT, 2-61, 3-14 
POPPAR, 2-61, 3-14 
Positive integer difference, 3-32 
Positive real difference, 2-20 
Positive real difference, 3-31 
Power 

scalar to scalar, 2-17, 2-18 
scalar to vector, 2-17, 2-18 
vector to scalar, 2-17, 2-18 
vector to vector, 2-17 2-18 

Power raised 

double-precision, 2-25 
double-precision, 2-26 
scalar /vector, 2-68 
single-precision, 2-46 

Power raised, 3-14, 3-16 

Powers of 10, 2-42, 2-82 

PPL, 2-60, 7-53 

PRBREAK, 2-96 

PRCW, 2-61, 5-54 

Preface, v 

Primary reference name, 1-1, 2-2 
Product inner, 4-9 
Prompt string, 2-96 
Pseudo vector iz at ion, 3-2 8 
PTS, 2-61, 7-20 
Publication list, v 
PUTBYT, 2-61, 7-65 
PUTWA, 2-90, 5-105 



Radix sort, 4-75 

Random access I/O, 5-8 3 

Random number, A-16 

Random number generator, 2-8 2 

Random number processing, 2-62 

Random number routines, 3-36 

RANF, 2-62, 3-36, A-16 

RANFI, 2-6 2, 2-82, 3-3 8 

RANFS, 2-62, 2-82, 3-38 

RANGET, 2-62, 3-36, A-17 

RANSET, 2-62, 3-36, A-17 

Rational number integer ceiling of, 2-41 

RB, 2-62, 5-8 

RBN, 2-6 3, 7-8 5 

RCFFT2, 2-31, 4-52 

RCHP, 2-63, 5-67 

RCHR, 2-63, 5-67 

RCWP, 2-63, 2-63 

RDIN, 2-63, 6-8 

RDYQUE, 2-6 3, 9-12 

RDYTSK, 2-63, 9-11 

Read 

asynchronously, 5-95, 5-108 
Boolean, 2-97 
buffer, 2-63 



Read (continued) 

buffered, 5-8, 5-17 

CDC file format, 5-18 

character, 5-66, 5-67, 2-97 

characters, 2-63, 2-64, 2-9 6 

characters, full record mode, 5-68 

characters, partial record mode, 5-68 

character record, 8-12 

directly from user area, 2-6 6 

floating-point, 2-97 

formatted, 5-3, 5-7, 2-66, 5-14 

formatted, vectorized, 5-8 

FORTRAN naraelist, 5-8 

IBM file format, 5-18 

IBM floating point words, 2-6 4 

IBM words, 5-69 

integer, 2-97 

list-directed, 2-67, 5-4, 5-14 

logical record, 8-6 

logical record in Al format, 7-58 

new line, 2-97 

one buffer of data, 6-8 

record, 2-96, 2-97, 8-13 

string, 2-97 

synchronous/asynchronous, 5-96 
unblocked data, 5-69 
unformatted, 2-6, 5-3, 5-7, 5-14 
unformatted, vectorized, 5-8 
words, 2-63, 2-64, 2-96, 5-110 
words, full record mode, 5-64, 5-6 6 
words, partial record mode, 5-64, 5-66 
READ, 2-64 

Read/write check, 2-28 
READC, 2-64, 5-68 
READCP, 2-64, 5-68 
READIBM, 2-64, 5-69 
READMS, 2-53 
READMS/READDR, 5-9 0 
READP, 2-64, 5-66 
Reads 

random access, 5-90 
READWA, 5-110 
REAL, 2-65, 3-34 
Real absolute value, 3-2 9 
Real array 

copies, 2-14 
Record 

backspace, 5-50 

logical I/O, 5-6 3 
Record format management 

input, 5-18 

output, 5-18 
Record mode writes characters in, 2-91 
Records 

bypass, 5-40 

copies, 2-15 

copy, 5-35 
RELEASE, 2-6 5, 6-3 
REMARK, 2-65, 7-87 
REMARK 2, 2-65, 7-87 
REMARKF, 2-65, 7-87 
Reprieve processing (Pascal), 2-96 
REPRIEVE processing, 2-65 
Reprieve processing, 2-97, 8-13 
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RERUN, 2-66, 7-37 

Reverse Polish Table, 2-11 

REWD, 2-66, 5-52 

REWIND, 5-53 

RFA, 5-7 

RFD, 2-66 

RFF, 5-14 

RFI, 5-3 

RFV, 5-7, 5-8 

Right shift, 3-14 

RLA, 2-67 

RLA read list-directed, 5-7 

RLB, 2-6 6, 5-69 

RLF, 2-67, 5-14 

RLI, 2-67, 5-4 

RNB, 2-67, 2-74, 7-85, 7-87 

RNL, 2-55, 5-8 

RNLCOMM, 2-55, 5-62 

RNLDELM, 2-55, 5-61 

RNLECHO, 2-55, 5-60 

RNLFLAG, 2-55, 5-61 

RNLREP, 2-55, 5-62 

RNLSEP, 2-55, 5-61 

RNLSKIP, 2-55, 5-60 

RNLTYPE , 2-5 5 , 5-60 

RTOI, 2-68, 3-16, A-17 

RTOR, 2-68, 3-16, A-18 

RUA, 2-69, 5-7 

RUF, 5-14 

RUI, 2-69, 5-3 

Runtime errors, 8-19 

Runtime initialization routine, 2-97 

Runtime messages, 2-97 

Runtime timing, 2-97, 2-97 

RUTD, 2-69, 5-17 

RUTDP, 2-69 

RUTF, 2-69, 5-17 

RUTI, 2-69, 5-16 

RUV, 2-69, 5-7, 5-8 

RWDP, 5-64 

RWDR, 5-64 



SASUM, 2-80, 4-3, 4-5 
SAVE, 2-70, 6-2 
SAXPY, 2-8, 4-3, 4-6 
Scalar functions, 1-1 
Scale array, 4-21 
SCASUM, 2-80, 4-3, 4-6 
SCATTER, 2-70, 4-57 
SCERP, 2-70, 7-62 
SCHED, 2-71, 9-13 
SCI, 5-78 

Scientific applications subprograms, 4-1 

SCNRM2, 2-71, 4-11, 4-3 

SCOPY, 2-14, 4-3, 4-8 

SDACCESS, 2-71, 6-3 

SDOT, 4-4, 4-9 

SDOT, SPDOT, 2-22 

SDSP, 2-71, 6-4 

Search bytes, 7-66 

Search routines, 4-57 

SECOND, 2-7 2, 7-43 



Sectors 

bypass, 5-42 

copy, 5-39 
SEEK, 2-90, 5-108 
SEGCALL, 2-72, 7-8 8 
Segmented program, 2-72, 7-88 
SEGRES, 2-7 2, 7-88 
Sense switch, 2-79, 7-88 
SENSEBT, 2-7 2, 7-40 
SENSEFI, 2-72, 7-39 
Set new length routines, 7-2 7 
SETBT, 2-73, 7-41 
SETBTS, 2-7 3, 7-42 
SETFI , 2-73, 7-39 
SETFIS, 7-40 

SETPLIMQ, 2-33, 2-73, 7-3 
SETPOS, 2-74, 5-49 
SETRPV, 2-65, 7-37 
SFN, 2-74 
SHIFT, 2-74, 3-14 
Shift left, 2-7 4, 2-7 5 
Shift right, 2-75 
SHIFTL, 2-75, 3-14 
SHIFTR, 2-75, 3-14 
SHRINK, 2-37, 7-31 
SIGN, 2-75, 3-35 
Sign 

transfer, 2-45 

transfer from one integer to 
another, 3-33 

transfer from one real number 
another, 3-35 
SIN, 2-75, 3-9 
Sine 

complex, A-7 

double-precision, 2-24 
Sine, 2-16, 2-75, 3-10, 3-9, A-5 
Sine, d.p. , hyperbolic, A-13 
SINH, 2-75, 3-11 
Skip sectors, 2-76 
Skip to first good data, 2-76 
SKIPBAD, 2-76, 5-76 
SKIPD, 2-76, 5-41 
SKIPF, 2-76, 5-40 
SKIPR, 2-76, 5-40 
SKIPU, 2-76, 5-42 
SKOL processing, 2-38, 2-39, 2-40 
SKOL run-time support, 7-56 
SLERP, 2-76, 7-62 
SLFT, 2-77, 6-4 
SMACH, 2-77, 4-29 
SMMVE, 2-82 
SNAP, 2-77, 7-7 
SNRM2, 2-77, 4-10, 4-3 
SOLR, 2-77, 4-34 
SOLR3, 2-78, 4-36 
SOLKN, 2-78, 4-35 
Sort 

bucket, 4-75 

fixed-length records, 2-5 8 
multipass, 4-76 
pocket, 4-75 
radix, 4-75 
Sort entry points, C-l 
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SORT ROUTINE, 4-73 

Sparse matrix primitives , 4-2 4 

SPAXPY, 2-8, 4-24 

Special purpose subprograms , 7-X 

SPODT, 4-24 

SPOS, 2-74 

SPOS, 5-46 

SQRT, 2-78, 3-7, A-19 

Square root complex, A- 8 

Square root routines, 3-7 

Square root, 2-78, A-19 

SRC, 2-79, 7-18 

SPOT, 2-67, 4-13, 4-4 

SROTG, 2-67, 4-11, 4-4 

SPOTM, 2-67, 4-19, 4-4 

SROTMG, 2-67, 4-13, 4-4 

SSCAL, 2-70, 4-21, 4-4 

SSUM, 2-80, 4-27 

SSWAP, 2-81, 4-23, 4-4 

SSWITCH, 2-79, 7-88 

Stack header control word, 7-21 

Stack management, 7-21 

Stack processing, 2-79, 2-9 7 

Stack walkback, 8-23 

STINDX, 2-53 

STINDX/STINDR, 5-93, 5-94 

STKCR, 2-79, 7-23 

STKDE, 2-79, 7-24 

STKOFEN , 2-79, 7-23 

STKUFCK, 2-79, 7-24 

STKUFEX , 2-79, 7-24 

STOP, 2-79, 7-38 

Store character item, 5-7 8 

STOREF, 2-48, 7-12 

STPOS, 2-7 4 , 5-47 

STRM0V r 2-80, 7-63 

Sub-index, 5-9 3 

SUBMIT, 2-80, 6-3 

Subprogram summary, 2-1 

Subroutine name address of, 2-35 

Subroutines prints a list, 2-85 

Subtraction double-precision, 2-23 

SUSTSK, 2-80, 9-12 

Symbolic dump, 2-81, 7-7 

SYMDEBDG , 2-81, 7-7 

SYNCH, 2-81, 5-55 

SYNCMS/SYNCDR, 5-96 

System clock, 2-13 
System directory, 6-3 
SYSTEM, 7-89 



Table 

clears space, 2-95 

move words to, 2-54 

permanent dataset definitions, 6-9 

preset space, 2-61 

search, 2-79 

search with mask, 2-53 
Table Base Table (BTAB) , 7-12 
Table Length Table (LTAB) , 7-12 
Table management, 7-12 
Table manager, 2-81 
Table of contents, vii 



Table pointers, 2-43 

Table space total allotted, 2-6 

TADD, 2-8 2, 3-18 

TAN, 2-83, 3-10 

Tangent, 2-83, 3-10 

Tangent, d .p. , A-14 

Tangent, hyperbolic, A-19 

Tangent, hyperbolic d.p., A-14 

TANH, 2-8 3, 3-11, A-19 

Tape dataset, 5-55 

Tape dataset position information, 5-44 
Tape translation 

buffer management, 5-16 

data format management, 5-18 

description, 5-15 

record format management, 5-18 

Task 

initiates, 2-85 

suspends execution, 2-80 
Task information block, 2-83 
Task routines, 9-1 
Task, 2-86 
Tasks 

read for execution, 2-63 
schedule logical CPUs for, 2-71 

TASS, 2-82, 3-18 

TDIV, 2-83, 3-19 

TDSS, 2-83, 3-19 

Temporarily prohibits 

floating-point interrupts, 2-13 

Terminate program, 2-96 

TIBCR, 2-83, 9-11 

TIBDE, 2-83, 9-11 

Time 

obtain, 2-96, 2-97 
since start of job, 2-7 2 

Time and date, 7-42 

TIMEF, 2-19, 7-43 

Timestamp routines, 7-44 

Timestamp units, 7-4 5 

Timestamp, 2-84 

TM common block, 7-14 

TMADW, 2-81, 7-16 

TMAMU, 2-81, 7-19 

TMATS , 2-81, 7-16 

TMINIT, 2-81, 7-15 

TMLT, 2-84, 3-19 

TMMEM, 2-82, 7-15 

TMMSC, 2-82, 7-17 

TMMVE, 7-21 

TMPTS, 2-82, 7-20 

TMSRC, 2-8 2, 7-18 

TMSS, 2-84, 3-19 

TMVSC, 2-82, 7-19 

TR, 2-84, 7-89 

Traceback, 2-85, 7-4 

Trailing blanks, 2-63 

Trailing nulls, 2-67, 2-74 

Transfer 

character to result, 2-11 

one character item to result, 3-24 

termination, 2-11, 3-25 

sign, 2-24, 2-45, 2-75, 3-32 
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Translate 

ASCII CDC display code, 5-20 

CDC d.p. to Cray a. p. f .p. , 5-19 

CDC f.p* to Cray f.p,, 5-19 

CDC complex to Cray complex f .p. , 5-19 

CDC display code to ASCII, 5-19 

CDC logical to Cray logical, 5-19 

Cray integer to CDC integer, 5-20 

Cray cLp. f.p. to CDC d.p. , 5-20 

Cray f.p. to CDC f.p., 5-20 

Cray complex f.p. to CDC complex, 5-20 

Cray logical to CDC logical, 5-20 

IBM complex f.p. to Cray complex 

f.p., 5-19, 5-20 
IBM integer to Cray integer, 5-19 
IBM logical to Cray logical, 5-19 
IBM f.p. to Cray f.p., 5-19 
IBM EBCDIC to ASCII, 5-19 
internal format, 5-18 

Tr anslates 

CDC formatted input, 2-11 
CDC formatted output, 2-11 
characters, 2-84 
IBM formatted data, 2-4 0 

TRBK, 2-85, 7-4 

TRBKLVL , 2-85, 7-4, 7-5 

T REMAIN, 2-85, 7-43 

Trigonometric routines, 3-10, 3-8, 3-9 
Triple-precision 

addition, 2-82, 3-18 

arithmetic routines, 3-19, 3-20, 3-18 

division, 2-83, 3-19 

multiplication, 2-84, 3-19 

subtraction, 2-86, 3-20 
True condition 

first location of, 2-45 
Truncate 

double-precision, 2-21 

double-precision numbers, 3-31 

to integral value, 3-29, 3-33 
TSDT, 2-84, 7-44 
TSKLIST, 9-7 
TSKSTART, 2-85, 9-1 
TSKTEST, 2-85, 9-4 
TSKTUNE, 2-86, 9-5 
TSKVALUE , 2-86, 9-4 
TSKWAIT, 2-86, 9-3 
TSMT, 2-84, 7-45 
TSSS, 2-86, 3-20 
TSUB, 2-86, 3-20 



U32, 2-86, 5-30 

U6064, 2-87, 5-29 

UEOFCL, 2-87 

UEOFKIL, 2-87, 5-59 

UEOFSET, 2-87, 5-59 

UEOPTCL, 5-59 

UIO, 5-78 

UNIT, 2-87, 5-57 

UNITTS, 2-84, 7-4 5 

Unpack 

3 2-bit words, 5-30 
60-bit words, 2-87, 5-2 9 



UNPACK, 2-87, 7-69 
Unpacks 32-bit words, 2-8 6 
Update deck name, 2-2 
USCCTC, 2-87, 5-2 2 
USCCTI, 2-88, 5-27 
USDCTC, 2-88, 5-21 
USDCTI, 2-88, 5-25 
USICTC, 2-88, 5-21 
USICTI, 2-89, 5-26 
USICTP, 2-88, 5-28 
USLCTC, 2-89, 5-23 
USLCTI, 2-89, 5-28 
USPCTC, 2-89, 5-23 
USSCTC, 2-89, 5-20 
USSCTI, 2-90, 5-24 
UTERP, 2-9 0, 7^-6 2 
Utility subprograms, 9-11 



Vector 

absolute values of, 4-5 

add a scalar multiple, 4-6 

complex, 4-6 

copy complex, 4-8 

false values in, 4-58 

gather, 2-3 5, 4-5 6 

largest absolute value of, 404 

largest or smallest element of, 4-2 5 

scale, 4-21 

scatter, 4-56 

smallest absolute value in, 2-45 

sum of values, 4-27 

true values, 4-58 

write to output, 2-9 2 
Vector functions, 1-1 
Vector ization 

pseudo, 3-28 
Vectors 

convolution, 4-54 

exchange, 4-23 



WAITMS/WAITDR, 5-98 

WB, 2-91, 5-13 

WCHK, 2-92 

WCHP, 2-91, 5-7 3 

WCHR, 2-91, 5-73 

WCIOSE, 2-9 0, 5-108 

WDSET, 5-111 

WDSETB, 5-111 

WEOD, 2-91, 5-56 

WEOF, 2-91, 5-5 6 

WFA, 2-92, 5-11 

WFBUFFER, 2-91, 7-8 9 

WFF, 2-92, 5-14 

WFI, 2-91, 5-4 

WFV, 2-91, 5-12 

WHEN routines, summary, 4-6 5 

WHENEQ, 2-92, 4-66 

WHENFGE , 2-92, 4-68 

WHENFGT, 2-92, 4-68 

WHENFLE , 2-9 2, 4-67 

WHENFLT, 2-92, 4-67 

WHENIGE, 2-92, 4-70 
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WHENIGT, 2-92, 4-70 
WHENILE, 2-9 2 , 4-69 
WHENILT, 2-92, 4-69 
WHENNE, 2-9 2, 4-66 
Whole number 

calculates nearest, 3-29 

nearest, 2-6 
WLA # 2-93, 5-12 
WLB, 2-92, 5-74 
WLF f 2-93, 5-15 
WLI, 2-9 3, 5-5 
WLV, 5-13 

WNL write FORTRAN namelist, 5-13 

WNL, 2-56 

WNLDELM, 5-62 

WNLFLAG, 5-63 

WNLLONG, 5-62 

WNLREP, 5-6 3 

WNLSEP, 5-63 

WNOCHK, 2-92 

WOPEN, 2-90, 5-103 

Write 

Boolean, 2-97 

Boolean argument, 8-2 4 

buffered, 5-13, 5-17 

CDC file format, 5-18 

characters, 2-96, 2-97, 8-24 

characters, full record mode, 5-7 3 f 5-74 

characters, partial record 
mode, 5-73, 5-74 

characters defined by the TYPE CHAR 
statement, 7-59 

character record, 8-14 

contents of exchange package, 7-9 

EOF, 2-96 

EOF, EOR, 5-56 

end-of-file, 2-97 

end of file mark, 8-2 5 

end-of-line, 2-97 

formatted, 2-92, 5-4, 5-11, 5-12, 5-14 

formatted, vectorized, 5-12 

floating-point, 2-94 

full record mode, 2-94 

IBM file format, 5-18 

IBM words , 5-74 

integer, 2-97 

into user area, 2-9 2 

list-directed, 2-93, 5-5, 5-12, 

5-13, 5-15 
logical record, 8-17 
octal integer, 2-97 
partial record mode, 2-93, 2-94 
real number, 2-97 
record, 2-96, 2-97, 8-15 
packed character string, 8-2 7 
record mode, 2-95 
string, 2-97 
unblocked data, 5-74 

unformatted, 2-9 4, 5-4, 5-11, 5-12, 5-15 
unformatted, vectorized, 5-12 
words, 5-110 

words, full record mode, 5-70, 5-71 
words, partial record mode, 5-70, 5-71 
WRITE, 2-93, 5-71 



WRITEC, 2-9 3, 5-7 4 

WRITECP, 2-93, 5-74 

WRITEP, 2-93, 5-71 

Wr ites 

master index, 5-91 
random access, 5-8 9 

WRITEWA, 5-110 

WR1TIBM, 2-94, 5-7 4 

WRITMS, 2-53 

WRITMS/WRITDR, 5-8 9 

WUA, 2-94, 5-11 

WUF, 2-94, 5-15 

WUI, 2-94, 5-4 

WUTD, 2-94, 5-17 

WUTDP, 2-94 

WUTF, 2-94, 5-18 

WUTI, 2-94, 5-17 

WUV, 2-9 4, 5-12 

WWDP, 2-95, 5-70 

WWDR, 2-95, 5-70 

WWDS, 2-95, 5-70 

WWPU, 2-95, 5-70 



XOR, 2-95, 3-14 
XPFMT, 2-30, 7-9 



Zero bits tally leading, 2-47 
Zero/nonzero, 2-42 
ZTS, 2-95, 7-20 
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